From 2ca7e3c4b0cb293adebf9a9bf9a26191069d495d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9ctor=20Ram=C3=B3n=20Jim=C3=A9nez?= Date: Thu, 28 May 2020 01:37:59 +0200 Subject: [PATCH] Write documentation for `iced_graphics` --- graphics/src/antialiasing.rs | 3 + graphics/src/backend.rs | 22 +++++ graphics/src/font.rs | 11 +++ graphics/src/font/source.rs | 8 ++ graphics/src/layer.rs | 115 ++++++++++++++++++++++++++- graphics/src/lib.rs | 10 +++ graphics/src/renderer.rs | 18 ++++- graphics/src/triangle.rs | 5 ++ graphics/src/viewport.rs | 22 +++++ graphics/src/widget/column.rs | 1 + graphics/src/widget/image.rs | 1 + graphics/src/widget/row.rs | 1 + graphics/src/widget/svg.rs | 1 + graphics/src/window.rs | 1 + graphics/src/window/gl_compositor.rs | 41 ++++++++++ wgpu/src/backend.rs | 3 +- wgpu/src/lib.rs | 10 ++- wgpu/src/widget.rs | 10 ++- wgpu/src/widget/text.rs | 7 -- 19 files changed, 271 insertions(+), 19 deletions(-) delete mode 100644 wgpu/src/widget/text.rs diff --git a/graphics/src/antialiasing.rs b/graphics/src/antialiasing.rs index f92b3692..34d94711 100644 --- a/graphics/src/antialiasing.rs +++ b/graphics/src/antialiasing.rs @@ -12,6 +12,9 @@ pub enum Antialiasing { } impl Antialiasing { + /// Returns the amount of samples of the [`Antialiasing`]. + /// + /// [`Antialiasing`]: enum.Antialiasing.html pub fn sample_count(self) -> u32 { match self { Antialiasing::MSAAx2 => 2, diff --git a/graphics/src/backend.rs b/graphics/src/backend.rs index ee4eca0a..83510311 100644 --- a/graphics/src/backend.rs +++ b/graphics/src/backend.rs @@ -1,15 +1,33 @@ +//! Write a graphics backend. use iced_native::image; use iced_native::svg; use iced_native::{Font, Size}; +/// The graphics backend of a [`Renderer`]. +/// +/// [`Renderer`]: ../struct.Renderer.html pub trait Backend { + /// Trims the measurements cache. + /// + /// This method is currently necessary to properly trim the text cache in + /// `iced_wgpu` and `iced_glow` because of limitations in the text rendering + /// pipeline. It will be removed in the future. fn trim_measurements(&mut self) {} } +/// A graphics backend that supports text rendering. pub trait Text { + /// The icon font of the backend. const ICON_FONT: Font; + + /// The `char` representing a ✔ icon in the [`ICON_FONT`]. + /// + /// [`ICON_FONT`]: #associatedconst.ICON_FONt const CHECKMARK_ICON: char; + /// Measures the text contents with the given size and font, + /// returning the size of a laid out paragraph that fits in the provided + /// bounds. fn measure( &self, contents: &str, @@ -19,10 +37,14 @@ pub trait Text { ) -> (f32, f32); } +/// A graphics backend that supports image rendering. pub trait Image { + /// Returns the dimensions of the provided image. fn dimensions(&self, handle: &image::Handle) -> (u32, u32); } +/// A graphics backend that supports SVG rendering. pub trait Svg { + /// Returns the viewport dimensions of the provided SVG. fn viewport_dimensions(&self, handle: &svg::Handle) -> (u32, u32); } diff --git a/graphics/src/font.rs b/graphics/src/font.rs index a490e609..bcc28857 100644 --- a/graphics/src/font.rs +++ b/graphics/src/font.rs @@ -1,22 +1,33 @@ +//! Find system fonts or use the built-in ones. #[cfg(feature = "font-source")] mod source; #[cfg(feature = "font-source")] +#[cfg_attr(docsrs, doc(cfg(feature = "font-source")))] pub use source::Source; #[cfg(feature = "font-source")] +#[cfg_attr(docsrs, doc(cfg(feature = "font-source")))] pub use font_kit::{ error::SelectionError as LoadError, family_name::FamilyName as Family, }; +/// A built-in fallback font, for convenience. #[cfg(feature = "font-fallback")] +#[cfg_attr(docsrs, doc(cfg(feature = "font-fallback")))] pub const FALLBACK: &[u8] = include_bytes!("../fonts/Lato-Regular.ttf"); +/// A built-in icon font, for convenience. #[cfg(feature = "font-icons")] +#[cfg_attr(docsrs, doc(cfg(feature = "font-icons")))] pub const ICONS: iced_native::Font = iced_native::Font::External { name: "iced_wgpu icons", bytes: include_bytes!("../fonts/Icons.ttf"), }; +/// The `char` representing a ✔ icon in the built-in [`ICONS`] font. +/// +/// [`ICONS`]: const.ICONS.html #[cfg(feature = "font-icons")] +#[cfg_attr(docsrs, doc(cfg(feature = "font-icons")))] pub const CHECKMARK_ICON: char = '\u{F00C}'; diff --git a/graphics/src/font/source.rs b/graphics/src/font/source.rs index 6855aa93..917291ff 100644 --- a/graphics/src/font/source.rs +++ b/graphics/src/font/source.rs @@ -1,16 +1,24 @@ use crate::font::{Family, LoadError}; +/// A font source that can find and load system fonts. +#[allow(missing_debug_implementations)] pub struct Source { raw: font_kit::source::SystemSource, } impl Source { + /// Creates a new [`Source`]. + /// + /// [`Source`]: struct.Source.html pub fn new() -> Self { Source { raw: font_kit::source::SystemSource::new(), } } + /// Finds and loads a font matching the set of provided family priorities. + /// + /// [`Source`]: struct.Source.html pub fn load(&self, families: &[Family]) -> Result, LoadError> { let font = self.raw.select_best_match( families, diff --git a/graphics/src/layer.rs b/graphics/src/layer.rs index 59b792f0..6aca738e 100644 --- a/graphics/src/layer.rs +++ b/graphics/src/layer.rs @@ -1,3 +1,4 @@ +//! Organize rendering primitives into a flattened list of layers. use crate::image; use crate::svg; use crate::triangle; @@ -6,16 +7,39 @@ use crate::{ Vector, VerticalAlignment, Viewport, }; +/// A group of primitives that should be clipped together. #[derive(Debug, Clone)] pub struct Layer<'a> { + /// The clipping bounds of the [`Layer`]. + /// + /// [`Layer`]: struct.Layer.html pub bounds: Rectangle, + + /// The quads of the [`Layer`]. + /// + /// [`Layer`]: struct.Layer.html pub quads: Vec, + + /// The triangle meshes of the [`Layer`]. + /// + /// [`Layer`]: struct.Layer.html pub meshes: Vec>, + + /// The text of the [`Layer`]. + /// + /// [`Layer`]: struct.Layer.html pub text: Vec>, + + /// The images of the [`Layer`]. + /// + /// [`Layer`]: struct.Layer.html pub images: Vec, } impl<'a> Layer<'a> { + /// Creates a new [`Layer`] with the given clipping bounds. + /// + /// [`Layer`]: struct.Layer.html pub fn new(bounds: Rectangle) -> Self { Self { bounds, @@ -26,6 +50,11 @@ impl<'a> Layer<'a> { } } + /// Creates a new [`Layer`] for the provided overlay text. + /// + /// This can be useful for displaying debug information. + /// + /// [`Layer`]: struct.Layer.html pub fn overlay(lines: &'a [impl AsRef], viewport: &Viewport) -> Self { let mut overlay = Layer::new(Rectangle::with_size(viewport.logical_size())); @@ -56,6 +85,10 @@ impl<'a> Layer<'a> { overlay } + /// Distributes the given [`Primitive`] and generates a list of layers based + /// on its contents. + /// + /// [`Primitive`]: ../enum.Primitive.html pub fn generate( primitive: &'a Primitive, viewport: &Viewport, @@ -119,7 +152,7 @@ impl<'a> Layer<'a> { bounds.x + translation.x, bounds.y + translation.y, ], - scale: [bounds.width, bounds.height], + size: [bounds.width, bounds.height], color: match background { Background::Color(color) => color.into_linear(), }, @@ -203,46 +236,124 @@ impl<'a> Layer<'a> { } } +/// A colored rectangle with a border. +/// +/// This type can be directly uploaded to GPU memory. #[derive(Debug, Clone, Copy)] #[repr(C)] pub struct Quad { + /// The position of the [`Quad`]. + /// + /// [`Quad`]: struct.Quad.html pub position: [f32; 2], - pub scale: [f32; 2], + + /// The size of the [`Quad`]. + /// + /// [`Quad`]: struct.Quad.html + pub size: [f32; 2], + + /// The color of the [`Quad`], in __linear RGB__. + /// + /// [`Quad`]: struct.Quad.html pub color: [f32; 4], + + /// The border color of the [`Quad`], in __linear RGB__. + /// + /// [`Quad`]: struct.Quad.html pub border_color: [f32; 4], + + /// The border radius of the [`Quad`]. + /// + /// [`Quad`]: struct.Quad.html pub border_radius: f32, + + /// The border width of the [`Quad`]. + /// + /// [`Quad`]: struct.Quad.html pub border_width: f32, } +/// A mesh of triangles. #[derive(Debug, Clone, Copy)] pub struct Mesh<'a> { + /// The origin of the vertices of the [`Mesh`]. + /// + /// [`Mesh`]: struct.Mesh.html pub origin: Point, + + /// The vertex and index buffers of the [`Mesh`]. + /// + /// [`Mesh`]: struct.Mesh.html pub buffers: &'a triangle::Mesh2D, + + /// The clipping bounds of the [`Mesh`]. + /// + /// [`Mesh`]: struct.Mesh.html pub clip_bounds: Rectangle, } +/// A paragraph of text. #[derive(Debug, Clone, Copy)] pub struct Text<'a> { + /// The content of the [`Text`]. + /// + /// [`Text`]: struct.Text.html pub content: &'a str, + + /// The layout bounds of the [`Text`]. + /// + /// [`Text`]: struct.Text.html pub bounds: Rectangle, + + /// The color of the [`Text`], in __linear RGB_. + /// + /// [`Text`]: struct.Text.html pub color: [f32; 4], + + /// The size of the [`Text`]. + /// + /// [`Text`]: struct.Text.html pub size: f32, + + /// The font of the [`Text`]. + /// + /// [`Text`]: struct.Text.html pub font: Font, + + /// The horizontal alignment of the [`Text`]. + /// + /// [`Text`]: struct.Text.html pub horizontal_alignment: HorizontalAlignment, + + /// The vertical alignment of the [`Text`]. + /// + /// [`Text`]: struct.Text.html pub vertical_alignment: VerticalAlignment, } +/// A raster or vector image. #[derive(Debug, Clone)] pub enum Image { + /// A raster image. Raster { + /// The handle of a raster image. handle: image::Handle, + + /// The bounds of the image. bounds: Rectangle, }, + /// A vector image. Vector { + /// The handle of a vector image. handle: svg::Handle, + + /// The bounds of the image. bounds: Rectangle, }, } +#[allow(unsafe_code)] unsafe impl bytemuck::Zeroable for Quad {} + +#[allow(unsafe_code)] unsafe impl bytemuck::Pod for Quad {} diff --git a/graphics/src/lib.rs b/graphics/src/lib.rs index 2de9d21c..b6dda132 100644 --- a/graphics/src/lib.rs +++ b/graphics/src/lib.rs @@ -1,3 +1,13 @@ +//! A bunch of backend-agnostic types that can be leveraged to build a renderer +//! for [`iced`]. +//! +//! [`iced`]: https://github.com/hecrj/iced +#![deny(missing_docs)] +#![deny(missing_debug_implementations)] +#![deny(unused_results)] +#![deny(unsafe_code)] +#![forbid(rust_2018_idioms)] +#![cfg_attr(docsrs, feature(doc_cfg))] mod antialiasing; mod defaults; mod primitive; diff --git a/graphics/src/renderer.rs b/graphics/src/renderer.rs index f16e04b1..c9360f3a 100644 --- a/graphics/src/renderer.rs +++ b/graphics/src/renderer.rs @@ -3,19 +3,33 @@ use iced_native::layout::{self, Layout}; use iced_native::mouse; use iced_native::{Background, Color, Element, Point, Widget}; -pub struct Renderer { +/// A backend-agnostic renderer that supports all the built-in widgets. +#[derive(Debug)] +pub struct Renderer { backend: B, } -impl Renderer { +impl Renderer { + /// Creates a new [`Renderer`] from the given [`Backend`]. + /// + /// [`Renderer`]: struct.Renderer.html + /// [`Backend`]: backend/trait.Backend.html pub fn new(backend: B) -> Self { Self { backend } } + /// Returns a reference to the [`Backend`] of the [`Renderer`]. + /// + /// [`Renderer`]: struct.Renderer.html + /// [`Backend`]: backend/trait.Backend.html pub fn backend(&self) -> &B { &self.backend } + /// Returns a mutable reference to the [`Backend`] of the [`Renderer`]. + /// + /// [`Renderer`]: struct.Renderer.html + /// [`Backend`]: backend/trait.Backend.html pub fn backend_mut(&mut self) -> &mut B { &mut self.backend } diff --git a/graphics/src/triangle.rs b/graphics/src/triangle.rs index 474f69b8..ce879ffc 100644 --- a/graphics/src/triangle.rs +++ b/graphics/src/triangle.rs @@ -1,3 +1,5 @@ +//! Draw geometry using meshes of triangles. + /// A set of [`Vertex2D`] and indices representing a list of triangles. /// /// [`Vertex2D`]: struct.Vertex2D.html @@ -23,5 +25,8 @@ pub struct Vertex2D { pub color: [f32; 4], } +#[allow(unsafe_code)] unsafe impl bytemuck::Zeroable for Vertex2D {} + +#[allow(unsafe_code)] unsafe impl bytemuck::Pod for Vertex2D {} diff --git a/graphics/src/viewport.rs b/graphics/src/viewport.rs index 745ef339..66122e6d 100644 --- a/graphics/src/viewport.rs +++ b/graphics/src/viewport.rs @@ -26,22 +26,44 @@ impl Viewport { } } + /// Returns the physical size of the [`Viewport`]. + /// + /// [`Viewport`]: struct.Viewport.html pub fn physical_size(&self) -> Size { self.physical_size } + /// Returns the physical width of the [`Viewport`]. + /// + /// [`Viewport`]: struct.Viewport.html + pub fn physical_width(&self) -> u32 { + self.physical_size.height + } + + /// Returns the physical height of the [`Viewport`]. + /// + /// [`Viewport`]: struct.Viewport.html pub fn physical_height(&self) -> u32 { self.physical_size.height } + /// Returns the logical size of the [`Viewport`]. + /// + /// [`Viewport`]: struct.Viewport.html pub fn logical_size(&self) -> Size { self.logical_size } + /// Returns the scale factor of the [`Viewport`]. + /// + /// [`Viewport`]: struct.Viewport.html pub fn scale_factor(&self) -> f64 { self.scale_factor } + /// Returns the projection transformation of the [`Viewport`]. + /// + /// [`Viewport`]: struct.Viewport.html pub fn projection(&self) -> Transformation { self.projection } diff --git a/graphics/src/widget/column.rs b/graphics/src/widget/column.rs index 9183d2ee..6c7235c7 100644 --- a/graphics/src/widget/column.rs +++ b/graphics/src/widget/column.rs @@ -3,6 +3,7 @@ use iced_native::column; use iced_native::mouse; use iced_native::{Element, Layout, Point}; +/// A container that distributes its contents vertically. pub type Column<'a, Message, Backend> = iced_native::Column<'a, Message, Renderer>; diff --git a/graphics/src/widget/image.rs b/graphics/src/widget/image.rs index ea49febe..30f446e8 100644 --- a/graphics/src/widget/image.rs +++ b/graphics/src/widget/image.rs @@ -1,3 +1,4 @@ +//! Display images in your user interface. use crate::backend::{self, Backend}; use crate::{Primitive, Renderer}; use iced_native::image; diff --git a/graphics/src/widget/row.rs b/graphics/src/widget/row.rs index 9865d0de..4c1dbadc 100644 --- a/graphics/src/widget/row.rs +++ b/graphics/src/widget/row.rs @@ -3,6 +3,7 @@ use iced_native::mouse; use iced_native::row; use iced_native::{Element, Layout, Point}; +/// A container that distributes its contents horizontally. pub type Row<'a, Message, Backend> = iced_native::Row<'a, Message, Renderer>; diff --git a/graphics/src/widget/svg.rs b/graphics/src/widget/svg.rs index 8c681478..8b5ed66a 100644 --- a/graphics/src/widget/svg.rs +++ b/graphics/src/widget/svg.rs @@ -1,3 +1,4 @@ +//! Display vector graphics in your application. use crate::backend::{self, Backend}; use crate::{Primitive, Renderer}; use iced_native::{mouse, svg, Layout}; diff --git a/graphics/src/window.rs b/graphics/src/window.rs index 380efb8c..3e74db5f 100644 --- a/graphics/src/window.rs +++ b/graphics/src/window.rs @@ -1,3 +1,4 @@ +//! Draw graphics to window surfaces. mod compositor; #[cfg(feature = "opengl")] diff --git a/graphics/src/window/gl_compositor.rs b/graphics/src/window/gl_compositor.rs index aea898e3..542213b5 100644 --- a/graphics/src/window/gl_compositor.rs +++ b/graphics/src/window/gl_compositor.rs @@ -3,19 +3,60 @@ use iced_native::mouse; use core::ffi::c_void; +/// A basic OpenGL compositor. +/// +/// A compositor is responsible for initializing a renderer and managing window +/// surfaces. +/// +/// For now, this compositor only deals with a single global surface +/// for drawing. However, the trait will most likely change in the near future +/// to handle multiple surfaces at once. +/// +/// If you implement an OpenGL renderer, you can implement this trait to ease +/// integration with existing windowing shells, like `iced_glutin`. pub trait GLCompositor: Sized { + /// The renderer of the [`Compositor`]. + /// + /// This should point to your renderer type, which could be a type alias + /// of the [`Renderer`] provided in this crate with with a specific + /// [`Backend`]. + /// + /// [`Compositor`]: trait.Compositor.html + /// [`Renderer`]: ../struct.Renderer.html + /// [`Backend`]: ../backend/trait.Backend.html type Renderer: iced_native::Renderer; + + /// The settings of the [`Compositor`]. + /// + /// It's up to you to decide the configuration supported by your renderer! type Settings: Default; + /// Creates a new [`Compositor`] and [`Renderer`] with the given + /// [`Settings`] and an OpenGL address loader function. + /// + /// [`Compositor`]: trait.Compositor.html + /// [`Renderer`]: #associatedtype.Renderer + /// [`Backend`]: ../backend/trait.Backend.html + #[allow(unsafe_code)] unsafe fn new( settings: Self::Settings, loader_function: impl FnMut(&str) -> *const c_void, ) -> (Self, Self::Renderer); + /// Returns the amount of samples that should be used when configuring + /// an OpenGL context for this [`Compositor`]. + /// + /// [`Compositor`]: trait.Compositor.html fn sample_count(settings: &Self::Settings) -> u32; + /// Resizes the viewport of the [`Compositor`]. + /// + /// [`Compositor`]: trait.Compositor.html fn resize_viewport(&mut self, physical_size: Size); + /// Draws the provided output with the given [`Renderer`]. + /// + /// [`Compositor`]: trait.Compositor.html fn draw>( &mut self, renderer: &mut Self::Renderer, diff --git a/wgpu/src/backend.rs b/wgpu/src/backend.rs index 04eb0b28..88529ddd 100644 --- a/wgpu/src/backend.rs +++ b/wgpu/src/backend.rs @@ -12,9 +12,10 @@ use iced_native::{Font, HorizontalAlignment, Size, VerticalAlignment}; #[cfg(any(feature = "image", feature = "svg"))] use crate::image; -/// A [`wgpu`] renderer. +/// A [`wgpu`] graphics backend for [`iced`]. /// /// [`wgpu`]: https://github.com/gfx-rs/wgpu-rs +/// [`iced`]: https://github.com/hecrj/iced #[derive(Debug)] pub struct Backend { quad_pipeline: quad::Pipeline, diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index b0eee0a0..0c351eea 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -20,7 +20,7 @@ //! [`wgpu`]: https://github.com/gfx-rs/wgpu-rs //! [WebGPU API]: https://gpuweb.github.io/gpuweb/ //! [`wgpu_glyph`]: https://github.com/hecrj/wgpu_glyph -//#![deny(missing_docs)] +#![deny(missing_docs)] #![deny(missing_debug_implementations)] #![deny(unused_results)] #![forbid(unsafe_code)] @@ -47,7 +47,11 @@ pub use widget::*; pub(crate) use iced_graphics::Transformation; -pub type Renderer = iced_graphics::Renderer; - #[cfg(any(feature = "image", feature = "svg"))] mod image; + +/// A [`wgpu`] graphics renderer for [`iced`]. +/// +/// [`wgpu`]: https://github.com/gfx-rs/wgpu-rs +/// [`iced`]: https://github.com/hecrj/iced +pub type Renderer = iced_graphics::Renderer; diff --git a/wgpu/src/widget.rs b/wgpu/src/widget.rs index ac741118..d17b7a5d 100644 --- a/wgpu/src/widget.rs +++ b/wgpu/src/widget.rs @@ -19,8 +19,6 @@ pub mod scrollable; pub mod slider; pub mod text_input; -mod text; - #[doc(no_inline)] pub use button::Button; #[doc(no_inline)] @@ -40,8 +38,6 @@ pub use slider::Slider; #[doc(no_inline)] pub use text_input::TextInput; -pub use text::Text; - #[cfg(feature = "canvas")] #[cfg_attr(docsrs, doc(cfg(feature = "canvas")))] pub mod canvas; @@ -52,5 +48,11 @@ pub use canvas::Canvas; pub use iced_native::Space; +/// A container that distributes its contents vertically. pub type Column<'a, Message> = iced_native::Column<'a, Message, Renderer>; + +/// A container that distributes its contents horizontally. pub type Row<'a, Message> = iced_native::Row<'a, Message, Renderer>; + +/// A paragraph of text. +pub type Text = iced_native::Text; diff --git a/wgpu/src/widget/text.rs b/wgpu/src/widget/text.rs deleted file mode 100644 index 1053ea97..00000000 --- a/wgpu/src/widget/text.rs +++ /dev/null @@ -1,7 +0,0 @@ -//! Write some text for your users to read. -use crate::Renderer; - -/// A paragraph of text. -/// -/// This is an alias of an `iced_native` text with an `iced_wgpu::Renderer`. -pub type Text = iced_native::Text;