Implement an initial version of Vello API #1299

DJMcNab · 2025-11-21T19:14:55Z

This is an initial implementation of Vello API, our abstraction between Vello CPU and Vello Hybrid (and also maybe Vello Classic).

A few notes:

This is designed to be combined with something like a "Parley Draw", i.e. it's designed to allow external glyph rendering.
The design is fully no_std + alloc compatible.
Vello API does not try to abstract away the unabstractable, e.g. handling external textures.
The multi-threading design is something which will need more thought. I think we're likely to end up with an explicit CommandEncoder like API, similarly to that seen in wgpu.

Importantly, this PR is intentionally not making internal changes to the extant crates, and instead is only adding new API surface for the abstraction. The plan would be to make these changes only once this has landed, to limit merge conflicts as much as possible.

I think it's valuable to get something landed here, whether or not it ends up being the final state. The main advantage there is that it allows porting tests in a piecemeal fashion, as well as making changes to the APIs of Vellos CPU and Hybrid (without creating a massive merge conflict headache). This PR is currently scoped small enough to be easily revertible if we want to go a different direction.

A previous version of this PR used the renderer abstraction for the tests. That code is now gone as it wasn't landable, but can be seen in b200d5e and earlier.

nicoburns · 2025-11-26T19:00:15Z

sparse_strips/vello_api/src/texture.rs

+    // TODO: Maybe a better type is `atomicow::CowArc<'static, str>`
+    pub label: Option<&'static str>,


https://lib.rs/crates/smol_str is another option here (Winit depends on it)

I'm wondering how much effort it would be to coordinate a UI-ecosystem-wide change to one of the other mini-string crates. IIRC some of them have more features.

Maybe at next RustWeek.

sparse_strips/vello_api/src/lib.rs

PoignardAzur

Overall, not sure how to think about this PR. It has a lot of TODO comments and hedges in places where we'll need to make judgment calls sooner or later.

sparse_strips/vello_api/src/painter.rs

PoignardAzur · 2025-12-29T14:09:07Z

sparse_strips/vello_api/src/painter.rs

+            // This needing to be turbofished shows a real footgun with the proped "push_layer" API here.
+            None::<BezPath>,


I don't think we'll solve this in the short-term, but this is definitely worth creating an issue about.

PoignardAzur · 2025-12-29T14:28:08Z

sparse_strips/vello_api/src/scene.rs

+// TODO: Change module and give a better name.
+pub type OurBrush = peniko::Brush<peniko::ImageBrush<TextureHandle>>;


I'd suggest "VelloBrush" for now.

PoignardAzur · 2025-12-29T14:36:00Z

sparse_strips/vello_api/src/painter.rs

+    fn push_layer(
+        &mut self,
+        clip_transform: Affine,
+        clip_path: Option<impl Shape>,
+        blend_mode: Option<BlendMode>,
+        opacity: Option<f32>,
+        // mask: Option<Mask>,
+        // filter: Option<Filter>
+    );


Is there any reason why the API doesn't let you add transform layers?

It isn't an existing feature in any of the Vellos {Classic, Hybrid, CPU}.

It also doesn't provide new functionality over the user manually keeping track of a transform externally, but it makes reasoning about a number of things more difficult (primarily drawing hinted glyphs, but also in the future how filter effects and masks will be applied).

Implementation wise, it's also a bit confused because it doesn't behave in the same way as any other layer type; i.e. it would be a layer type which doesn't implement a new isolated context, unless you set any of the other fields.

PoignardAzur · 2025-12-29T14:37:54Z

sparse_strips/vello_api/src/scene.rs

+        self.commands
+            .extend(other_commands.iter().map(|command| match command {
+                RenderCommand::DrawPath(transform, path) => {
+                    RenderCommand::DrawPath(correct_transform(*transform), correct_path(*path))
+                }
+                RenderCommand::PushLayer(command) => RenderCommand::PushLayer(PushLayerCommand {
+                    clip_transform: correct_transform(command.clip_transform),
+                    clip_path: command.clip_path.map(correct_path),
+                    blend_mode: command.blend_mode,
+                    opacity: command.opacity,
+                }),
+                RenderCommand::PopLayer => RenderCommand::PopLayer,
+                RenderCommand::SetPaint(affine, brush) => {
+                    // Don't update the paint_transform, as it's already path local.
+                    RenderCommand::SetPaint(*affine, brush.clone())
+                }
+                RenderCommand::BlurredRoundedRectPaint(brush) => {
+                    // Don't update the paint_transform, as it's (currently) already path local.
+                    RenderCommand::BlurredRoundedRectPaint(brush.clone())
+                }
+            }));


For example, seems like this block of code could be replaced with a transform layer.

I don't think that's true; this code is equivalent to the implementation of Scene::append in Vello Classic. That code would still need to exist in a version of this proposal with transform layers; the path references still need to be updated.

The only part of this code which would change is the two calls to correct_transform; instead those would be handled by the transform layer.

PoignardAzur · 2025-12-29T14:41:46Z

sparse_strips/vello_api/src/texture.rs

+    // TODO: Format? Premultiplication? Hdr?
+    // TODO: Explicit atlasing?


If you're not sure what fields you'll add, this struct should be #[non_exhaustive].

Can you clarify how you expect this to work, if users need to create this struct?

This type mirrors the descriptors from wgpu, which aren't non_exhaustive.
Hopefully we get default_field_values soon enough, ideally with a nice non_exhaustive story.

PoignardAzur · 2025-12-29T14:49:57Z

sparse_strips/vello_api/src/scene.rs

+#[derive(Debug)]
+pub struct Scene {
+    pub paths: PathSet,
+    pub commands: Vec<RenderCommand>,
+    // TODO: Make this an `Option`? That is, allow explicitly renderer-agnostic scenes
+    // which also don't allow bringing in textures?
+    pub renderer: Arc<dyn Renderer>,
+    pub hinted: bool,
+    /// Handles for each texture stored in this scene.
+    ///
+    /// We store these to ensure that the textures won't be freed until this scene
+    /// is fully rendered (and dropped).
+    // TODO: HashSet? We'd need to bring in hashbrown, but that's probably fine
+    pub textures: Vec<TextureHandle>,
+}


The Scene type needs way more documentation. As it is, I don't know how it's supposed to be used, how it fields relate to each other, what assumptions it makes that mustn't be broken, etc.

It's especially not clear to me how Scene and PathSet relate. Does each scene store its own set of paths? Doesn't that kind of defeat the point of path caching?

It's especially not clear to me how Scene and PathSet relate. Does each scene store its own set of paths? Doesn't that kind of defeat the point of path caching?

Sure, this is definitely under-documented. I'm planning to spend the time to add some more docs as my near-term priority here.

Essentially, each Scene accumulates the paths which it's drawing. These can either be copied into any painters which the scene is used in, to be rasterised in a just-in-time manner, or moved into the renderer (i.e. cached).
This accumulation pattern is designed to avoid an allocation for each path, whilst still allowing reference-count based garbage collection for cached paths (they are reference counted as a group of "related" paths).

But whilst PathSet currently exists for that design, the caching is not yet implemented (as it doesn't actually exist in the underlying renderers, for one). But I feel it still makes sense as an abstraction boundary to have, albeit with better docs...

DJMcNab force-pushed the api-design branch 2 times, most recently from b200d5e to a48f6c5 Compare November 26, 2025 18:45

DJMcNab changed the title ~~Implement an initial version of Vello API, and implement most of the sparse strip tests using it~~ Implement an initial version of Vello API Nov 26, 2025

nicoburns reviewed Nov 26, 2025

View reviewed changes

dominikh reviewed Dec 4, 2025

View reviewed changes

sparse_strips/vello_api/src/lib.rs Outdated Show resolved Hide resolved

DJMcNab force-pushed the api-design branch from e8aacd8 to dbaa21b Compare December 5, 2025 16:06

DJMcNab force-pushed the api-design branch from b57728c to 8ae3736 Compare December 19, 2025 14:59

DJMcNab marked this pull request as ready for review December 19, 2025 14:59

taj-p self-requested a review December 21, 2025 20:51

grebmeg self-requested a review December 22, 2025 02:47

PoignardAzur reviewed Dec 29, 2025

View reviewed changes

DJMcNab added 17 commits December 30, 2025 10:43

Add the initial version of Vello API

1b7afab

Add it to Vello CPU

ab1bccf

Add it to Vello Hybrid

94abc09

Fix Webgl/Wasm

819fa30

Sketch out a major rethink of the API around recordings and paths

dd61bd3

Theorise about interior mutability tweaks

f533a46

Push some more changes about how paths are referenced

d52fa0e

Stash changes

03a6f1c

Move design to a markdown file

dd0d666

Perform a cleanup drive

c3fde70

Setup the texture refcounting

ae1599e

Add high-level docs for textures, etc.

39bed8f

Draft further the use of TextureHandle

2341c4e

Add some more docs

2f3e020

Port Vellos CPU and Hybrid to the latest API

d031ed2

Get some test infra kind of in place

d0ea9cc

Port the "basic" set of tests

f2b527d

DJMcNab force-pushed the api-design branch from 8ae3736 to f2b527d Compare December 30, 2025 10:50

Address review concerns around TODOs

eb9e697

DJMcNab added 5 commits December 30, 2025 14:30

Remove unresolved comment

207a460

Fixup order of derives

b4cf1a1

Fix sentence fragment

c28deb1

Add some more docs

9b131d8

Add some docs to PathSet

07c629a

		// TODO: Maybe a better type is `atomicow::CowArc<'static, str>`
		pub label: Option<&'static str>,

		// This needing to be turbofished shows a real footgun with the proped "push_layer" API here.
		None::<BezPath>,

		// TODO: Change module and give a better name.
		pub type OurBrush = peniko::Brush<peniko::ImageBrush<TextureHandle>>;

		// TODO: Format? Premultiplication? Hdr?
		// TODO: Explicit atlasing?

Implement an initial version of Vello API #1299

Are you sure you want to change the base?

Implement an initial version of Vello API #1299

Uh oh!

Conversation

DJMcNab commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

PoignardAzur left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DJMcNab Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DJMcNab Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

DJMcNab commented Nov 21, 2025 •

edited

Loading

DJMcNab Dec 30, 2025 •

edited

Loading

DJMcNab Dec 30, 2025 •

edited

Loading