vello_cpu: Unify render APIs

sparse_strips/vello_bench/src/glyph.rs

@@ -9,7 +9,7 @@ use parley::{
     PositionedLayoutItem,
 };
 use vello_common::pixmap::Pixmap;
-use vello_cpu::{Glyph, RenderContext, RenderMode, RenderSettings, Resources};
+use vello_cpu::{Glyph, RasterizerSettings, RenderContext, RenderSettings, Resources};
 
 pub fn glyph(c: &mut Criterion) {
     let mut g = c.benchmark_group("glyph");
@@ -30,10 +30,7 @@ pub fn glyph(c: &mut Criterion) {
         layout
     };
 
-    let settings = RenderSettings {
-        render_mode: RenderMode::OptimizeSpeed,
-        ..Default::default()
-    };
+    let settings = RenderSettings::default();
     let layout = layout_for(TEXT, 1.0);
 
     for (hint_name, hint) in [("hinted", true), ("unhinted", false)] {
@@ -114,9 +111,11 @@ fn render_layout(
         }
     }
 
-    renderer
-        .ctx
-        .render_to_pixmap(&mut renderer.resources, &mut renderer.pixmap);
+    renderer.ctx.render(
+        &mut renderer.pixmap,
+        &mut renderer.resources,
+        RasterizerSettings::default(),
+    );
 }
 
 fn render_glyph_run(

sparse_strips/vello_bench/src/integration.rs

@@ -12,7 +12,7 @@ use vello_common::peniko::ImageSampler;
 use vello_common::peniko::{Extend, ImageQuality};
 use vello_common::pixmap::Pixmap;
 use vello_cpu::color::AlphaColor;
-use vello_cpu::{RenderContext, Resources};
+use vello_cpu::{RasterizerSettings, RenderContext, Resources};
 
 /// Image scene rendering benchmark.
 pub fn images(c: &mut Criterion) {
@@ -57,7 +57,7 @@ pub fn images(c: &mut Criterion) {
             }
 
             renderer.flush();
-            renderer.render_to_pixmap(&mut resources, &mut pixmap);
+            renderer.render(&mut pixmap, &mut resources, RasterizerSettings::default());
             std::hint::black_box(&pixmap);
         });
     });

sparse_strips/vello_common/src/pixmap.rs

@@ -29,6 +29,51 @@ pub struct Pixmap {
     may_have_transparency: bool,
 }
 
+/// A mutable view into premultiplied RGBA8 pixmap data.
+#[derive(Debug)]
+pub struct PixmapMut<'a> {
+    /// Width of the pixmap in pixels.
+    width: u16,
+    /// Height of the pixmap in pixels.
+    height: u16,
+    /// Buffer of the pixmap in RGBA8 format.
+    buf: &'a mut [u8],
+}
+
+impl<'a> PixmapMut<'a> {
+    /// Create a new mutable pixmap view.
+    ///
+    /// Returns `None` if `buf` is not exactly `width * height * 4` bytes long.
+    pub fn new(width: u16, height: u16, buf: &'a mut [u8]) -> Option<Self> {
+        if buf.len() == usize::from(width) * usize::from(height) * 4 {
+            Some(Self { width, height, buf })
+        } else {
+            None
+        }
+    }
+
+    /// Return the width of the pixmap.
+    pub fn width(&self) -> u16 {
+        self.width
+    }
+
+    /// Return the height of the pixmap.
+    pub fn height(&self) -> u16 {
+        self.height
+    }
+
+    /// Returns a mutable reference to the underlying data as premultiplied RGBA8 bytes.
+    pub fn data_mut(&mut self) -> &mut [u8] {
+        self.buf
+    }
+}
+
+impl<'a> From<&'a mut Pixmap> for PixmapMut<'a> {
+    fn from(pixmap: &'a mut Pixmap) -> Self {
+        pixmap.as_mut()
+    }
+}
+
 impl Pixmap {
     /// Create a new pixmap with the given width and height in pixels.
     ///
@@ -293,6 +338,10 @@ impl Pixmap {
         &self.buf
     }
 
+    // TODO: Now that we have `as_mut`, maybe we don't need the
+    // mutable methods. If we add a `PixmapRef` we can also remove the
+    // non-mutable ones.
+
     /// Returns a mutable reference to the underlying data as premultiplied RGBA8.
     ///
     /// The pixels are in row-major order.
@@ -316,6 +365,15 @@ impl Pixmap {
         bytemuck::cast_slice_mut(&mut self.buf)
     }
 
+    /// Return a mutable view into this pixmap's pixel data.
+    pub fn as_mut(&mut self) -> PixmapMut<'_> {
+        PixmapMut {
+            width: self.width,
+            height: self.height,
+            buf: bytemuck::cast_slice_mut(&mut self.buf),
+        }
+    }
+
     /// Sample a pixel from the pixmap.
     ///
     /// The pixel data is [premultiplied RGBA8][PremulRgba8].

sparse_strips/vello_cpu/README.md

@@ -29,7 +29,7 @@ See https://linebender.org/blog/doc-include/ for related discussion. -->
 [RenderContext::glyph_run]: https://docs.rs/vello_cpu/latest/vello_cpu/struct.RenderContext.html#method.glyph_run
 [RenderMode::OptimizeSpeed]: https://docs.rs/vello_cpu/latest/vello_cpu/enum.RenderMode.html#variant.OptimizeSpeed
 [RenderMode::OptimizeQuality]: https://docs.rs/vello_cpu/latest/vello_cpu/enum.RenderMode.html#variant.OptimizeQuality
-[`RenderContext::render_to_pixmap`]: https://docs.rs/vello_cpu/latest/vello_cpu/struct.RenderContext.html#method.render_to_pixmap
+[`RenderContext::render`]: https://docs.rs/vello_cpu/latest/vello_cpu/struct.RenderContext.html#method.render
 [`Pixmap`]: https://docs.rs/vello_cpu/latest/vello_cpu/struct.Pixmap.html
 
 <!-- cargo-rdme start -->
@@ -43,15 +43,15 @@ Vello CPU is being developed as part of work to address shortcomings in Vello.
 
 To use Vello CPU, you need to:
 
-- Create a [`RenderContext`][], a 2D drawing context for a fixed-size target area.
+- Create a [`RenderContext`][], a 2D drawing context for a fixed-size scene area.
 - For each object in your scene:
   - Set how the object will be painted, using [`set_paint`][RenderContext::set_paint].
   - Set the shape to be drawn for that object, using methods like [`fill_path`][RenderContext::fill_path],
     [`stroke_path`][RenderContext::stroke_path], or [`glyph_run`][RenderContext::glyph_run].
-- Render it to an image using [`RenderContext::render_to_pixmap`][].
+- Render it to an image using [`RenderContext::render`][].
 
 ```rust
-use vello_cpu::{RenderContext, Resources, Pixmap, RenderMode};
+use vello_cpu::{RasterizerSettings, RenderContext, Resources, Pixmap};
 use vello_cpu::{color::{palette::css, PremulRgba8}, kurbo::Rect};
 let width = 10;
 let height = 5;
@@ -64,7 +64,7 @@ let mut target = Pixmap::new(width, height);
 // While calling `flush` is only strictly necessary if you are rendering using
 // multiple threads, it is recommended to always do this.
 context.flush();
-context.render_to_pixmap(&mut resources, &mut target);
+context.render(&mut target, &mut resources, RasterizerSettings::default());
 
 let expected_render = b"\
     0000000000\

sparse_strips/vello_cpu/examples/basic.rs

@@ -8,7 +8,7 @@
 use vello_cpu::color::palette::css::YELLOW;
 use vello_cpu::kurbo::Affine;
 use vello_cpu::{
-    Level, Pixmap, RenderContext, RenderMode, RenderSettings, Resources,
+    Level, Pixmap, RasterizerSettings, RenderContext, RenderMode, RenderSettings, Resources,
     color::palette::css::{BLUE, GREEN, RED},
     kurbo::{Circle, Rect, Shape},
 };
@@ -52,6 +52,8 @@ fn main() {
         // using 4+ threads might result in diminishing results, depending on
         // the workload.
         num_threads: 0,
+    };
+    let rasterizer_settings = RasterizerSettings {
         // Define whether the renderer should prioritize speed or quality
         // during rendering. Currently, the only difference is that
         // `OptimizeSpeed` will use u8/u16 for the rasterization
@@ -60,6 +62,7 @@ fn main() {
         // worse due to quantization. Unless you really care about that, it is
         // highly recommended to use the `OptimizeSpeed` rendering mode.
         render_mode: RenderMode::OptimizeSpeed,
+        ..Default::default()
     };
 
     // Vello CPU embraces a slightly different paradigm than a lot of other 2D
@@ -126,12 +129,12 @@ fn main() {
 
     // Now the second step is to copy the results of the render context into the
     // pixmap. We do this by creating a new pixmap (or reusing an existing one).
-    // Please note that the pixmap and the render context need to have the same
-    // dimensions! Otherwise, the renderer will panic.
+    // The pixmap and render context can have different dimensions. See the documentation
+    // of the `render` method for more information.
     let mut pixmap_1 = Pixmap::new(100, 100);
     // Now, simply extract the results from the render context into the
     // pixmap.
-    ctx.render_to_pixmap(&mut resources, &mut pixmap_1);
+    ctx.render(&mut pixmap_1, &mut resources, rasterizer_settings);
 
     // Now you can do whatever you want with the pixmap, which provides raw
     // access to the premultiplied RGBA pixels of the image. If you have enabled
@@ -155,11 +158,11 @@ fn main() {
 
     // Once again, we render the results into a pixmap again. If you can,
     // you can just reuse existing pixmaps (assuming they have the correct
-    // dimension), since all previous pixels in the pixmap will be
-    // discarded. In our case, we need to create a new one since our call
-    // to `into_png` consumed the pixmap.
+    // dimension), since all previous pixels in the pixmap will be cleared by
+    // the default replace mode. In our case, we need to create a new one since
+    // our call to `into_png` consumed the pixmap.
     let mut pixmap_2 = Pixmap::new(100, 100);
-    ctx.render_to_pixmap(&mut resources, &mut pixmap_2);
+    ctx.render(&mut pixmap_2, &mut resources, rasterizer_settings);
     let png_2 = pixmap_2.into_png().unwrap();
     std::fs::write("example_basic2.png", png_2).unwrap();
 }

sparse_strips/vello_cpu/examples/clipping.rs

@@ -4,6 +4,7 @@
 //! Applying clip paths using Vello CPU.
 
 use vello_cpu::Pixmap;
+use vello_cpu::RasterizerSettings;
 use vello_cpu::RenderContext;
 use vello_cpu::Resources;
 use vello_cpu::color::palette::css::{BLUE, RED, WHITE};
@@ -128,7 +129,7 @@ fn main() {
 fn save_pixmap(ctx: &RenderContext, filename: &str) {
     let mut resources = Resources::new();
     let mut pixmap = Pixmap::new(ctx.width(), ctx.height());
-    ctx.render_to_pixmap(&mut resources, &mut pixmap);
+    ctx.render(&mut pixmap, &mut resources, RasterizerSettings::default());
     let png = pixmap.into_png().unwrap();
     std::fs::write(format!("{filename}.png"), png).unwrap();
 }

sparse_strips/vello_cpu/examples/masking.rs

@@ -5,7 +5,7 @@
 
 use vello_cpu::color::palette::css::{BLUE, RED, WHITE};
 use vello_cpu::kurbo::Rect;
-use vello_cpu::{Mask, Pixmap, RenderContext, Resources};
+use vello_cpu::{Mask, Pixmap, RasterizerSettings, RenderContext, Resources};
 
 const SIZE: u16 = 200;
 
@@ -25,7 +25,11 @@ fn main() {
         mask_ctx.set_paint(RED);
         mask_ctx.fill_rect(&Rect::new(30.0, 30.0, 170.0, 170.0));
         mask_ctx.flush();
-        mask_ctx.render_to_pixmap(&mut mask_resources, &mut pixmap);
+        mask_ctx.render(
+            &mut pixmap,
+            &mut mask_resources,
+            RasterizerSettings::default(),
+        );
 
         Mask::new_luminance(&pixmap)
     };
@@ -94,7 +98,7 @@ fn main() {
 fn save_pixmap(ctx: &RenderContext, filename: &str) {
     let mut resources = Resources::new();
     let mut pixmap = Pixmap::new(ctx.width(), ctx.height());
-    ctx.render_to_pixmap(&mut resources, &mut pixmap);
+    ctx.render(&mut pixmap, &mut resources, RasterizerSettings::default());
     let png = pixmap.into_png().unwrap();
     std::fs::write(format!("{filename}.png"), png).unwrap();
 }

sparse_strips/vello_cpu/examples/paints.rs

@@ -6,7 +6,7 @@
 use std::sync::Arc;
 use std::{io::Cursor, path::Path};
 use vello_cpu::{
-    Image, ImageSource, Pixmap, RenderContext, Resources,
+    Image, ImageSource, Pixmap, RasterizerSettings, RenderContext, Resources,
     color::palette::css::{BLUE, CYAN, DEEP_PINK, MAGENTA, NAVY, ORANGE, PURPLE, WHITE, YELLOW},
     kurbo::{Affine, Point, Rect},
     peniko::{
@@ -135,7 +135,7 @@ fn pattern() -> Image {
 fn save_pixmap(ctx: &RenderContext, filename: &str) {
     let mut resources = Resources::new();
     let mut pixmap = Pixmap::new(ctx.width(), ctx.height());
-    ctx.render_to_pixmap(&mut resources, &mut pixmap);
+    ctx.render(&mut pixmap, &mut resources, RasterizerSettings::default());
     let png = pixmap.into_png().unwrap();
     std::fs::write(format!("{filename}.png"), png).unwrap();
 }

sparse_strips/vello_cpu/examples/wasm_cpu/src/lib.rs

@@ -13,7 +13,7 @@ use std::rc::Rc;
 use std::{cell::RefCell, sync::Arc};
 use vello_common::kurbo::{Affine, Vec2};
 use vello_common::paint::ImageSource;
-use vello_cpu::RenderContext;
+use vello_cpu::{RasterizerSettings, RenderContext};
 use vello_example_scenes::{AnyScene, image::ImageScene};
 use wasm_bindgen::prelude::*;
 use web_sys::{Event, HtmlCanvasElement, KeyboardEvent, MouseEvent, WheelEvent};
@@ -72,9 +72,10 @@ impl AppState {
         self.scenes[self.current_scene].render(&mut self.renderer, self.transform);
 
         // Render the current scene with transform
-        self.renderer.render_to_pixmap(
-            self.scenes[self.current_scene].resources_mut(),
+        self.renderer.render(
             &mut self.pixmap,
+            self.scenes[self.current_scene].resources_mut(),
+            RasterizerSettings::default(),
         );
         let rgba_bytes = self.pixmap.data_as_u8_slice();
         let image_data = web_sys::ImageData::new_with_u8_clamped_array_and_sh(

sparse_strips/vello_cpu/examples/winit/src/main.rs

@@ -16,7 +16,7 @@ use std::time::Instant;
 use vello_common::kurbo::{Affine, Point};
 use vello_common::paint::ImageSource;
 use vello_common::pixmap::Pixmap;
-use vello_cpu::{RenderContext, RenderSettings};
+use vello_cpu::{RasterizerSettings, RenderContext, RenderSettings};
 use vello_example_scenes::image::ImageScene;
 use vello_example_scenes::{AnyScene, Capabilities, get_example_scenes};
 use winit::{
@@ -457,9 +457,10 @@ impl ApplicationHandler for App {
 
                 self.scenes[self.current_scene].render(&mut self.renderer, self.transform);
                 self.renderer.flush();
-                self.renderer.render_to_pixmap(
-                    self.scenes[self.current_scene].resources_mut(),
+                self.renderer.render(
                     &mut self.pixmap,
+                    self.scenes[self.current_scene].resources_mut(),
+                    RasterizerSettings::default(),
                 );
 
                 // Copy pixmap to window surface

sparse_strips/vello_cpu/src/dispatch/mod.rs

@@ -5,7 +5,7 @@
 pub(crate) mod multi_threaded;
 pub(crate) mod single_threaded;
 
-use crate::RenderMode;
+use crate::RasterizerSettings;
 use crate::kurbo::{Affine, BezPath, Rect, Stroke};
 use crate::peniko::{BlendMode, Fill};
 use core::fmt::Debug;
@@ -14,6 +14,7 @@ use vello_common::encode::EncodedPaint;
 use vello_common::filter_effects::Filter;
 use vello_common::mask::Mask;
 use vello_common::paint::{ImageResolver, Paint};
+use vello_common::pixmap::PixmapMut;
 
 pub(crate) trait Dispatcher: Debug + Send + Sync {
     fn wide(&self) -> &Wide;
@@ -72,23 +73,10 @@ pub(crate) trait Dispatcher: Debug + Send + Sync {
     fn flush(&mut self, encoded_paints: &[EncodedPaint]);
     fn rasterize(
         &self,
-        buffer: &mut [u8],
-        render_mode: RenderMode,
-        width: u16,
-        height: u16,
-        encoded_paints: &[EncodedPaint],
-        image_resolver: &dyn ImageResolver,
-    );
-    fn composite_at_offset(
-        &self,
-        buffer: &mut [u8],
-        width: u16,
-        height: u16,
-        dst_x: u16,
-        dst_y: u16,
-        dst_buffer_width: u16,
-        dst_buffer_height: u16,
-        render_mode: RenderMode,
+        target: PixmapMut<'_>,
+        scene_width: u16,
+        scene_height: u16,
+        settings: RasterizerSettings,
         encoded_paints: &[EncodedPaint],
         image_resolver: &dyn ImageResolver,
     );