Write documentation for iced_graphics

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<Quad>,
+
+    /// The triangle meshes of the [`Layer`].
+    ///
+    /// [`Layer`]: struct.Layer.html
     pub meshes: Vec<Mesh<'a>>,
+
+    /// The text of the [`Layer`].
+    ///
+    /// [`Layer`]: struct.Layer.html
     pub text: Vec<Text<'a>>,
+
+    /// The images of the [`Layer`].
+    ///
+    /// [`Layer`]: struct.Layer.html
     pub images: Vec<Image>,
 }
 
 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<str>], 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<f32>,
 }
 
+/// 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 {}