Auto merge of #391 - pcwalton:docs-renderer-2, r=pcwalton

Document the remainder of the `pathfinder_renderer` API

Author: bors-servo

export/src/lib.rs

@@ -11,7 +11,7 @@
 use pathfinder_content::outline::ContourIterFlags;
 use pathfinder_content::segment::SegmentKind;
 use pathfinder_geometry::vector::{Vector2F, vec2f};
-use pathfinder_renderer::scene::{DrawPath, Scene};
+use pathfinder_renderer::scene::{DrawPathId, Scene};
 use std::fmt;
 use std::io::{self, Write};
 
@@ -53,13 +53,15 @@ fn export_svg<W: Write>(scene: &Scene, writer: &mut W) -> io::Result<()> {
         view_box.size().x(),
         view_box.size().y()
     )?;
-    for &DrawPath { paint: paint_id, ref outline, ref name, .. } in scene.draw_paths() {
-        let paint = scene.get_paint(paint_id);
+    for draw_path_index in 0..scene.draw_path_count() {
+        let draw_path_id = DrawPathId(draw_path_index);
+        let draw_path = scene.get_draw_path(draw_path_id);
+        let paint = scene.get_paint(draw_path.paint);
         write!(writer, "    <path")?;
-        if !name.is_empty() {
-            write!(writer, " id=\"{}\"", name)?;
+        if !draw_path.name.is_empty() {
+            write!(writer, " id=\"{}\"", draw_path.name)?;
         }
-        writeln!(writer, " fill=\"{:?}\" d=\"{:?}\" />", paint, outline)?;
+        writeln!(writer, " fill=\"{:?}\" d=\"{:?}\" />", draw_path.paint, draw_path.outline)?;
     }
     writeln!(writer, "</svg>")?;
     Ok(())
@@ -76,14 +78,17 @@ fn export_pdf<W: Write>(scene: &Scene, writer: &mut W) -> io::Result<()> {
         vec2f(r.x(), height - r.y())
     };
 
-    for &DrawPath { paint: paint_id, ref outline, .. } in scene.draw_paths() {
+    for draw_path_index in 0..scene.draw_path_count() {
+        let draw_path_id = DrawPathId(draw_path_index);
+        let draw_path = scene.get_draw_path(draw_path_id);
+
         // TODO(pcwalton): Gradients and patterns.
-        let paint = scene.get_paint(paint_id);
+        let paint = scene.get_paint(draw_path.paint);
         if paint.is_color() {
             pdf.set_fill_color(paint.base_color());
         }
 
-        for contour in outline.contours() {
+        for contour in draw_path.outline.contours() {
             for (segment_index, segment) in contour.iter(ContourIterFlags::empty()).enumerate() {
                 if segment_index == 0 {
                     pdf.move_to(tr(segment.baseline.from()));
@@ -140,14 +145,16 @@ fn export_ps<W: Write>(scene: &Scene, writer: &mut W) -> io::Result<()> {
     writeln!(writer, "0 {} translate", view_box.size().y())?;
     writeln!(writer, "1 -1 scale")?;
 
-    for &DrawPath { paint: paint_id, ref outline, ref name, .. } in scene.draw_paths() {
-        if !name.is_empty() {
-            writeln!(writer, "newpath % {}", name)?;
+    for draw_path_index in 0..scene.draw_path_count() {
+        let draw_path_id = DrawPathId(draw_path_index);
+        let draw_path = scene.get_draw_path(draw_path_id);
+        if !draw_path.name.is_empty() {
+            writeln!(writer, "newpath % {}", draw_path.name)?;
         } else {
             writeln!(writer, "newpath")?;
         }
 
-        for contour in outline.contours() {
+        for contour in draw_path.outline.contours() {
             for (segment_index, segment) in contour.iter(ContourIterFlags::empty()).enumerate() {
                 if segment_index == 0 {
                     writeln!(writer, "{} moveto", P(segment.baseline.from()))?;
@@ -182,7 +189,7 @@ fn export_ps<W: Write>(scene: &Scene, writer: &mut W) -> io::Result<()> {
         }
 
         // TODO(pcwalton): Gradients and patterns.
-        let paint = scene.get_paint(paint_id);
+        let paint = scene.get_paint(draw_path.paint);
         if paint.is_color() {
             let color = paint.base_color();
             writeln!(writer, "{} {} {} setrgbcolor", color.r, color.g, color.b)?;

renderer/src/gpu/options.rs

@@ -32,6 +32,11 @@ pub struct RendererOptions<D> where D: Device {
     pub show_debug_ui: bool,
 }
 
+/// The GPU API level that Pathfinder will use.
+///
+/// Note that this is a *level*, not a *backend*. Levels describe rough GPU feature requirements
+/// instead of specific APIs. "D3D9" doesn't mean "Direct3D 9" specifically: rather, it's a more
+/// convenient way to write something like "Direct3D 9/OpenGL 3.0/Metal/WebGL 2.0".
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum RendererLevel {
     /// Direct3D 9/OpenGL 3.0/WebGL 2.0 compatibility. Bin on CPU, fill and composite on GPU.
@@ -41,6 +46,7 @@ pub enum RendererLevel {
 }
 
 impl RendererMode {
+    /// Creates a new `RendererMode` with a suitable API level for the given GPU device.
     #[inline]
     pub fn default_for_device<D>(device: &D) -> RendererMode where D: Device {
         RendererMode { level: RendererLevel::default_for_device(device) }

renderer/src/gpu/renderer.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! The GPU renderer that processes commands necessary to render a scene.
+
 use crate::gpu::blend::{ToBlendState, ToCompositeCtrl};
 use crate::gpu::d3d9::renderer::RendererD3D9;
 use crate::gpu::d3d11::renderer::RendererD3D11;
@@ -66,6 +68,7 @@ const COMBINER_CTRL_COLOR_FILTER_SHIFT: i32 =       4;
 const COMBINER_CTRL_COLOR_COMBINE_SHIFT: i32 =      6;
 const COMBINER_CTRL_COMPOSITE_SHIFT: i32 =          8;
 
+/// The GPU renderer that processes commands necessary to render a scene.
 pub struct Renderer<D> where D: Device {
     // Basic data
     pub(crate) core: RendererCore<D>,

renderer/src/gpu_data.rs

@@ -242,7 +242,7 @@ pub struct DrawTileBatchD3D11 {
 pub struct TileBatchTexture {
     pub page: TexturePageId,
     pub sampling_flags: TextureSamplingFlags,
-    pub composite_op: PaintCompositeOp,
+    pub(crate) composite_op: PaintCompositeOp,
 }
 
 #[derive(Clone, Copy, PartialEq, Debug)]

renderer/src/lib.rs

@@ -8,7 +8,9 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! The CPU portion of Pathfinder's renderer.
+//! Pathfinder's renderer and associated objects.
+
+#![warn(missing_docs)]
 
 #[macro_use]
 extern crate bitflags;

renderer/src/paint.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Defines how a path is to be filled.
+
 use crate::allocator::{AllocationMode, TextureAllocator};
 use crate::gpu_data::{ColorCombineMode, RenderCommand, TextureLocation, TextureMetadataEntry};
 use crate::gpu_data::{TexturePageDescriptor, TexturePageId, TileBatchTexture};
@@ -48,34 +50,46 @@ struct RenderTargetData {
     metadata: RenderTargetMetadata,
 }
 
+/// Defines how a path is to be filled: with a solid color, gradient, or pattern.
 #[derive(Clone, PartialEq, Eq, Hash, Debug)]
 pub struct Paint {
     base_color: ColorU,
     overlay: Option<PaintOverlay>,
 }
 
+/// What is to be overlaid on top of a base color.
+///
+/// An overlay is a gradient or a pattern, plus a composite operation which determines how the
+/// gradient or pattern is to be combined with the base color.
 #[derive(Clone, PartialEq, Eq, Hash, Debug)]
 pub struct PaintOverlay {
     composite_op: PaintCompositeOp,
     contents: PaintContents,
 }
 
+/// The contents of an overlay: either a gradient or a pattern.
 #[derive(Clone, PartialEq, Eq, Hash)]
-pub enum PaintContents {
+pub(crate) enum PaintContents {
+    /// A gradient, either linear or radial.
     Gradient(Gradient),
+    /// A raster image pattern.
     Pattern(Pattern),
 }
 
+/// The ID of a paint, unique to a scene.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub struct PaintId(pub u16);
 
+/// The ID of a gradient, unique to a scene.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub struct GradientId(pub u32);
 
-/// How a paint is to be composited over a base color, or vice versa.
+/// How an overlay is to be composited over a base color.
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 pub enum PaintCompositeOp {
+    /// The source that overlaps the destination, replaces the destination.
     SrcIn,
+    /// Destination which overlaps the source, replaces the source.
     DestIn,
 }
 
@@ -102,11 +116,13 @@ impl Palette {
 }
 
 impl Paint {
+    /// Creates a simple paint from a single base color.
     #[inline]
     pub fn from_color(color: ColorU) -> Paint {
         Paint { base_color: color, overlay: None }
     }
 
+    /// Creates a paint from a gradient.
     #[inline]
     pub fn from_gradient(gradient: Gradient) -> Paint {
         Paint {
@@ -118,6 +134,7 @@ impl Paint {
         }
     }
 
+    /// Creates a paint from a raster pattern.
     #[inline]
     pub fn from_pattern(pattern: Pattern) -> Paint {
         Paint {
@@ -129,16 +146,21 @@ impl Paint {
         }
     }
 
+    /// A convenience function to create a solid black paint.
     #[inline]
     pub fn black() -> Paint {
         Paint::from_color(ColorU::black())
     }
 
+    /// A convenience function to create a transparent paint with all channels set to zero.
     #[inline]
     pub fn transparent_black() -> Paint {
         Paint::from_color(ColorU::transparent_black())
     }
 
+    /// Returns true if this paint is obviously opaque, via a quick check.
+    ///
+    /// Even if the paint is opaque, this function might return false.
     pub fn is_opaque(&self) -> bool {
         if !self.base_color.is_opaque() {
             return false;
@@ -155,6 +177,9 @@ impl Paint {
         }
     }
 
+    /// Returns true if this paint is fully transparent, via a quick check.
+    ///
+    /// Even if the paint is fully transparent, this function might return false.
     pub fn is_fully_transparent(&self) -> bool {
         if !self.base_color.is_fully_transparent() {
             return false;
@@ -171,11 +196,15 @@ impl Paint {
         }
     }
 
+    /// Returns true if this paint represents a solid color.
     #[inline]
     pub fn is_color(&self) -> bool {
         self.overlay.is_none()
     }
 
+    /// Applies an affine transform to this paint.
+    ///
+    /// This has no effect if this paint is a solid color.
     pub fn apply_transform(&mut self, transform: &Transform2F) {
         if transform.is_identity() {
             return;
@@ -189,26 +218,36 @@ impl Paint {
         }
     }
 
+    /// Returns the *base color* of this paint.
+    ///
+    /// The base color is the color that goes underneath the gradient or pattern, if there is one.
     #[inline]
     pub fn base_color(&self) -> ColorU {
         self.base_color
     }
 
+    /// Changes the *base color* of this paint.
+    ///
+    /// The base color is the color that goes underneath the gradient or pattern, if there is one.
     #[inline]
     pub fn set_base_color(&mut self, new_base_color: ColorU) {
         self.base_color = new_base_color;
     }
 
+    /// Returns the paint overlay, which is the portion of the paint on top of the base color.
     #[inline]
     pub fn overlay(&self) -> &Option<PaintOverlay> {
         &self.overlay
     }
 
+    /// Returns a mutable reference to the paint overlay, which is the portion of the paint on top
+    /// of the base color.
     #[inline]
     pub fn overlay_mut(&mut self) -> &mut Option<PaintOverlay> {
         &mut self.overlay
     }
 
+    /// Returns the pattern, if this paint represents one.
     #[inline]
     pub fn pattern(&self) -> Option<&Pattern> {
         match self.overlay {
@@ -222,6 +261,7 @@ impl Paint {
         }
     }
 
+    /// Returns a mutable reference to the pattern, if this paint represents one.
     #[inline]
     pub fn pattern_mut(&mut self) -> Option<&mut Pattern> {
         match self.overlay {
@@ -235,6 +275,7 @@ impl Paint {
         }
     }
 
+    /// Returns the gradient, if this paint represents one.
     #[inline]
     pub fn gradient(&self) -> Option<&Gradient> {
         match self.overlay {
@@ -251,18 +292,22 @@ impl Paint {
 
 impl PaintOverlay {
     #[inline]
-    pub fn contents(&self) -> &PaintContents {
+    pub(crate) fn contents(&self) -> &PaintContents {
         &self.contents
     }
 
+    /// Returns the composite operation, which defines how the overlay is to be composited on top
+    /// of the base color.
     #[inline]
     pub fn composite_op(&self) -> PaintCompositeOp {
         self.composite_op
     }
 
+    /// Changes the composite operation, which defines how the overlay is to be composited on top
+    /// of the base color.
     #[inline]
     pub fn set_composite_op(&mut self, new_composite_op: PaintCompositeOp) {
-        self.composite_op = new_composite_op
+        self.composite_op = new_composite_op;
     }
 }