Auto merge of rust-windowing#427 - pcwalton:content-docs, r=pcwalton

Document the rest of `pathfinder_content`

Author: bors-servo

content/src/effects.rs

@@ -55,6 +55,7 @@ pub enum Filter {
         uv_origin: Vector2F,
     },
 
+    /// One of the `PatternFilter` filters.
     PatternFilter(PatternFilter),
 }
 
@@ -80,7 +81,9 @@ pub enum PatternFilter {
     /// To produce a full Gaussian blur, perform two successive blur operations, one in each
     /// direction.
     Blur {
+        /// The axis of the blur: horizontal or vertical.
         direction: BlurDirection,
+        /// Half the blur radius.
         sigma: f32,
     },
 
@@ -95,43 +98,86 @@ pub enum PatternFilter {
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub enum BlendMode {
     // Porter-Duff, supported by GPU blender
+    /// No regions are enabled.
     Clear,
+    /// Only the source will be present.
     Copy,
+    /// The source that overlaps the destination, replaces the destination.
     SrcIn,
+    /// Source is placed, where it falls outside of the destination.
     SrcOut,
+    /// Source is placed over the destination.
     SrcOver,
+    /// Source which overlaps the destination, replaces the destination. Destination is placed
+    /// elsewhere.
     SrcAtop,
+    /// Destination which overlaps the source, replaces the source.
     DestIn,
+    /// Destination is placed, where it falls outside of the source.
     DestOut,
+    /// Destination is placed over the source.
     DestOver,
+    /// Destination which overlaps the source replaces the source. Source is placed elsewhere.
     DestAtop,
+    /// The non-overlapping regions of source and destination are combined.
     Xor,
+    /// Display the sum of the source image and destination image. It is defined in the Porter-Duff
+    /// paper as the plus operator.
     Lighter,
 
     // Others, unsupported by GPU blender
+    /// Selects the darker of the backdrop and source colors.
     Darken,
+    /// Selects the lighter of the backdrop and source colors.
     Lighten,
+    /// The source color is multiplied by the destination color and replaces the destination.
     Multiply,
+    /// Multiplies the complements of the backdrop and source color values, then complements the
+    /// result.
     Screen,
+    /// Multiplies or screens the colors, depending on the source color value. The effect is
+    /// similar to shining a harsh spotlight on the backdrop.
     HardLight,
+    /// Multiplies or screens the colors, depending on the backdrop color value.
     Overlay,
+    /// Brightens the backdrop color to reflect the source color.
     ColorDodge,
+    /// Darkens the backdrop color to reflect the source color.
     ColorBurn,
+    /// Darkens or lightens the colors, depending on the source color value. The effect is similar
+    /// to shining a diffused spotlight on the backdrop.
     SoftLight,
+    /// Subtracts the darker of the two constituent colors from the lighter color.
     Difference,
+    /// Produces an effect similar to that of the Difference mode but lower in contrast.
     Exclusion,
+    /// Creates a color with the hue of the source color and the saturation and luminosity of the
+    /// backdrop color.
     Hue,
+    /// Creates a color with the saturation of the source color and the hue and luminosity of the
+    /// backdrop color.
     Saturation,
+    /// Creates a color with the hue and saturation of the source color and the luminosity of the
+    /// backdrop color.
     Color,
+    /// Creates a color with the luminosity of the source color and the hue and saturation of the
+    /// backdrop color. This produces an inverse effect to that of the Color mode.
     Luminosity,
 }
 
+/// The convolution kernel that will be applied horizontally to reduce color fringes when
+/// performing subpixel antialiasing. This kernel is automatically mirrored horizontally. The
+/// fourth element of this kernel is applied to the center of the pixel, the third element is
+/// applied one pixel to the left, and so on.
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub struct DefringingKernel(pub [f32; 4]);
 
+/// The axis a Gaussian blur is applied to.
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub enum BlurDirection {
+    /// The horizontal axis.
     X,
+    /// The vertical axis.
     Y,
 }
 

content/src/gradient.rs

@@ -22,27 +22,45 @@ use std::convert;
 use std::hash::{Hash, Hasher};
 use std::mem;
 
+/// A gradient, either linear or radial.
 #[derive(Clone, PartialEq, Debug)]
 pub struct Gradient {
+    /// Information specific to the type of gradient (linear or radial).
     pub geometry: GradientGeometry,
     stops: Vec<ColorStop>,
+    /// What should be rendered upon reaching the end of the color stops.
     pub wrap: GradientWrap,
 }
 
+/// A color in a gradient. Points in a gradient between two stops interpolate linearly between the
+/// stops.
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub struct ColorStop {
+    /// The offset of the color stop, between 0.0 and 1.0 inclusive. The value 0.0 represents the
+    /// start of the gradient, and 1.0 represents the end.
     pub offset: f32,
+    /// The color of the gradient stop.
     pub color: ColorU,
 }
 
+/// The type of gradient: linear or radial.
 #[derive(Clone, PartialEq, Debug)]
 pub enum GradientGeometry {
+    /// A linear gradient that follows a line.
+    ///
+    /// The line is in scene coordinates, not relative to the bounding box of the path.
     Linear(LineSegment2F),
+    /// A radial gradient that radiates outward from a line connecting two circles (or from one
+    /// circle).
     Radial {
-        /// The line that connects the two circles. It may have zero length for simple radial
-        /// gradients.
+        /// The line that connects the centers of the two circles. For single-circle radial
+        /// gradients (the common case), this line has zero length, with start point and endpoint
+        /// both at the circle's center point.
+        ///
+        /// This is in scene coordinates, not relative to the bounding box of the path.
         line: LineSegment2F,
-        /// The radii of the two circles. The first value may be zero.
+        /// The radii of the two circles. The first value may be zero to start the gradient at the
+        /// center of the circle.
         radii: F32x2,
         /// Transform from radial gradient space into screen space.
         ///
@@ -52,9 +70,13 @@ pub enum GradientGeometry {
     }
 }
 
+/// What should be rendered outside the color stops.
 #[derive(Clone, Copy, PartialEq, Debug)]
 pub enum GradientWrap {
+    /// The area before the gradient is filled with the color of the first stop, and the area after
+    /// the gradient is filled with the color of the last stop.
     Clamp,
+    /// The gradient repeats indefinitely.
     Repeat,
 }
 
@@ -97,6 +119,9 @@ impl Hash for ColorStop {
 }
 
 impl Gradient {
+    /// Creates a new linear gradient with the given line.
+    ///
+    /// The line is in scene coordinates, not relative to the bounding box of the current path.
     #[inline]
     pub fn linear(line: LineSegment2F) -> Gradient {
         Gradient {
@@ -106,11 +131,19 @@ impl Gradient {
         }
     }
 
+    /// A convenience method equivalent to `Gradient::linear(LineSegment2F::new(from, to))`.
     #[inline]
     pub fn linear_from_points(from: Vector2F, to: Vector2F) -> Gradient {
         Gradient::linear(LineSegment2F::new(from, to))
     }
 
+    /// Creates a new radial gradient from a line connecting the centers of two circles with the
+    /// given radii, or a point at the center of one circle.
+    ///
+    /// To create a radial gradient with a single circle (the common case), pass a `Vector2F`
+    /// representing the center of the circle for `line`; otherwise, to create a radial gradient
+    /// with two circles, pass a `LineSegment2F`. To start the gradient at the center of the
+    /// circle, pass zero for the first radius.
     #[inline]
     pub fn radial<L>(line: L, radii: F32x2) -> Gradient where L: RadialGradientLine {
         let transform = Transform2F::default();
@@ -121,6 +154,7 @@ impl Gradient {
         }
     }
 
+    /// Adds a new color stop to the radial gradient.
     #[inline]
     pub fn add(&mut self, stop: ColorStop) {
         let index = self.stops.binary_search_by(|other| {
@@ -129,22 +163,28 @@ impl Gradient {
         self.stops.insert(index, stop);
     }
 
-    /// A convenience method to add a color stop.
+    /// A convenience method equivalent to
+    /// `gradient.add_color_stop(ColorStop::new(color, offset))`.
     #[inline]
     pub fn add_color_stop(&mut self, color: ColorU, offset: f32) {
         self.add(ColorStop::new(color, offset))
     }
 
+    /// Returns the list of color stops in this gradient.
     #[inline]
     pub fn stops(&self) -> &[ColorStop] {
         &self.stops
     }
 
+    /// Returns a mutable version of the list of color stops in this gradient.
     #[inline]
     pub fn stops_mut(&mut self) -> &mut [ColorStop] {
         &mut self.stops
     }
 
+    /// Returns the value of the gradient at offset `t`, which will be clamped between 0.0 and 1.0.
+    ///
+    /// FIXME(pcwalton): This should probably take `wrap` into account…
     pub fn sample(&self, mut t: f32) -> ColorU {
         if self.stops.is_empty() {
             return ColorU::transparent_black();
@@ -170,16 +210,23 @@ impl Gradient {
         lower_stop.color.to_f32().lerp(upper_stop.color.to_f32(), ratio).to_u8()
     }
 
+    /// Returns true if all colors of all stops in this gradient are opaque (alpha is 1.0).
     #[inline]
     pub fn is_opaque(&self) -> bool {
         self.stops.iter().all(|stop| stop.color.is_opaque())
     }
 
+    /// Returns true if all colors of all stops in this gradient are fully transparent (alpha is
+    /// 0.0).
     #[inline]
     pub fn is_fully_transparent(&self) -> bool {
         self.stops.iter().all(|stop| stop.color.is_fully_transparent())
     }
 
+    /// Applies the given affine transform to this gradient.
+    ///
+    /// FIXME(pcwalton): This isn't correct for radial gradients, as transforms can transform the
+    /// circles into ellipses…
     pub fn apply_transform(&mut self, new_transform: Transform2F) {
         if new_transform.is_identity() {
             return;
@@ -195,13 +242,16 @@ impl Gradient {
 }
 
 impl ColorStop {
+    /// Creates a new color stop from a color and offset between 0.0 and 1.0 inclusive.
     #[inline]
     pub fn new(color: ColorU, offset: f32) -> ColorStop {
         ColorStop { color, offset }
     }
 }
 
+/// Allows `Gradient::radial` to be called with either a `LineSegment2F` or a `Vector2F`.
 pub trait RadialGradientLine {
+    /// Represents this value as a line.
     fn to_line(self) -> LineSegment2F;
 }
 

content/src/lib.rs

@@ -10,6 +10,8 @@
 
 //! Components of a vector scene, and various path utilities.
 
+#![warn(missing_docs)]
+
 #[macro_use]
 extern crate bitflags;
 #[macro_use]

content/src/orientation.rs

@@ -8,15 +8,22 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Determining whether an outline is wound clockwise or counterclockwise.
+
 use crate::outline::Outline;
 
+/// Winding order: counterclockwise or clockwise, with Y down.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum Orientation {
+    /// Counterclockwise, with Y down.
     Ccw = -1,
+    /// Clockwise, with Y down.
     Cw = 1,
 }
 
 impl Orientation {
+    /// Determines whether the outermost winding of an outline is counterclockwise or clockwise.
+    ///
     /// This follows the FreeType algorithm.
     pub fn from_outline(outline: &Outline) -> Orientation {
         let mut area = 0.0;

content/src/pattern.rs

@@ -36,9 +36,15 @@ pub struct Pattern {
 /// Where a raster image pattern comes from.
 #[derive(Clone, PartialEq, Eq, Hash, Debug)]
 pub enum PatternSource {
+    /// A image whose pixels are stored in CPU memory.
     Image(Image),
+    /// Previously-rendered vector content.
+    ///
+    /// This value allows you to render content and then later use that content as a pattern.
     RenderTarget {
+        /// The ID of the render target, including the ID of the scene it came from.
         id: RenderTargetId,
+        /// The device pixel size of the render target.
         size: Vector2I,
     }
 }

content/src/render_target.rs

@@ -8,10 +8,13 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Render targets.
+//! Raster images that vector graphics can be rendered to and later used as a pattern.
 
+/// Identifies a drawing surface for vector graphics that can be later used as a pattern.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub struct RenderTargetId {
+    /// The ID of the scene that this render target ID belongs to.
     pub scene: u32,
+    /// The ID of the render target within this scene.
     pub render_target: u32,
 }