Add a more ergonomic API for texture overrides

Signed-off-by: Nico Burns <nico@nicoburns.com>

vello/src/lib.rs

diff --git a/vello/src/lib.rs b/vello/src/lib.rs
index f127ac1..db2037e 100644
--- a/vello/src/lib.rs
+++ b/vello/src/lib.rs
@@ -312,6 +312,15 @@
 )]
 pub(crate) type Result<T, E = Error> = std::result::Result<T, E>;
 
+/// An opaque handle to a texture registered with [`Renderer::register_texture`] that
+/// can be passed to [`Scene::draw_texture`] to draw the texture.
+#[derive(Copy, Clone, PartialEq, Hash)]
+pub struct TextureHandle {
+    pub(crate) id: u64,
+    pub(crate) width: u32,
+    pub(crate) height: u32,
+}
+
 /// Renders a scene into a texture or surface.
 ///
 /// Currently, each renderer only supports a single surface format, if it
@@ -520,6 +529,7 @@
     /// dimensions would be rendered.
     ///
     /// [data]: peniko::Image::data
+    #[deprecated = "Use register_texture and unregister_texture methods instead"]
     pub fn override_image(
         &mut self,
         image: &peniko::Image,
@@ -531,6 +541,40 @@
         }
     }
 
+    /// Register a [`wgpu::Texture`] with Vello. You will receive a [`TextureHandle`] which
+    /// can be used to draw the registered texture using [`Scene::draw_texture`]
+    ///
+    /// If the texture is no longer active then it should be unregistered using [`unregister_texture`](Self::unregister_texture)
+    pub fn register_texture(&mut self, texture: wgpu::Texture) -> TextureHandle {
+        // Generate a unique ID using peniko::Blob to guarantee it won't clash
+        // with a user-generated image Blob
+        let id = peniko::Blob::<()>::new(std::sync::Arc::new(&[])).id();
+
+        let handle = TextureHandle {
+            id,
+            width: texture.width(),
+            height: texture.height(),
+        };
+
+        // Create a texture base for the texture
+        let texture_base = wgpu::TexelCopyTextureInfoBase {
+            texture,
+            mip_level: 0,
+            origin: wgpu::Origin3d::ZERO,
+            aspect: wgpu::TextureAspect::All,
+        };
+
+        // Insert it into the overrides map
+        self.engine.image_overrides.insert(id, texture_base);
+
+        handle
+    }
+
+    /// Unregister a [`wgpu::Texture`] that was registered with [`register_texture`](Self::register_texture)
+    pub fn unregister_texture(&mut self, handle: TextureHandle) {
+        self.engine.image_overrides.remove(&handle.id);
+    }
+
     /// Reload the shaders. This should only be used during `vello` development
     #[cfg(feature = "hot_reload")]
     #[doc(hidden)] // End-users of Vello should not have `hot_reload` enabled.

vello/src/scene.rs

diff --git a/vello/src/scene.rs b/vello/src/scene.rs
index 0e5f3ed..320c701 100644
--- a/vello/src/scene.rs
+++ b/vello/src/scene.rs
@@ -23,6 +23,8 @@
 use vello_encoding::BumpAllocatorMemory;
 use vello_encoding::{Encoding, Glyph, GlyphRun, NormalizedCoord, Patch, Transform};
 
+use crate::TextureHandle;
+
 // TODO - Document invariants and edge cases (#470)
 // - What happens when we pass a transform matrix with NaN values to the Scene?
 // - What happens if a push_layer isn't matched by a pop_layer?
@@ -306,6 +308,58 @@
         );
     }
 
+    /// Draws a texture at its natural size with the given transform
+    ///
+    /// To get a [`TextureHandle`] to use with this API, first register the texture with the renderer
+    /// using the [`Renderer::register_texture`](crate::Renderer::register_texture) method.
+    pub fn draw_texture(&mut self, handle: TextureHandle, transform: Affine) {
+        self.fill_texture(
+            Fill::NonZero,
+            transform,
+            1.0,
+            handle,
+            None,
+            &Rect::new(0.0, 0.0, handle.width as f64, handle.height as f64),
+            Extend::Pad,
+            Extend::Pad,
+        );
+    }
+
+    /// Fills a shape using the specified texture
+    ///
+    /// To get a [`TextureHandle`] to use with this API, first register the texture with the renderer
+    /// using the [`Renderer::register_texture`](crate::Renderer::register_texture) method.
+    pub fn fill_texture(
+        &mut self,
+        style: Fill,
+        transform: Affine,
+        alpha: f32,
+        handle: TextureHandle,
+        brush_transform: Option<Affine>,
+        shape: &impl Shape,
+        x_extend: Extend,
+        y_extend: Extend,
+    ) {
+        let dummy_image = Image {
+            data: Blob::from_raw_parts(Arc::new([]), handle.id),
+            width: handle.width,
+            height: handle.height,
+            format: peniko::ImageFormat::Rgba8,
+            quality: peniko::ImageQuality::High,
+            x_extend,
+            y_extend,
+            alpha,
+        };
+
+        self.fill(
+            style,
+            transform,
+            BrushRef::Image(&dummy_image),
+            brush_transform,
+            shape,
+        );
+    }
+
     /// Returns a builder for encoding a glyph run.
     pub fn draw_glyphs(&mut self, font: &Font) -> DrawGlyphs<'_> {
         // TODO: Integrate `BumpEstimator` with the glyph cache.