Implement an initial version of Vello API by DJMcNab · Pull Request #1299 · linebender/vello

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...

grebmeg · 2026-01-14T04:24:11Z

Great job, @DJMcNab. This looks like a strong foundational implementation, and designing a unified API is genuinely hard work. I haven’t dived deeply into the details yet, but I did a brief skim.

My initial impression, which might be off, is that this PR introduces a lot of new abstractions and concepts at once. Because of that density, I worry that once this lands it may effectively become the finished API, with some parts receiving less thorough review than they deserve. At the same time, many of these new concepts could naturally spark discussion across different consumers.

Not sure if this is feasible, but would it be possible to extract some of the core logic into multiple, smaller PRs and introduce things iteratively? That could make reviews simpler, reduce cognitive load, and ultimately improve review quality. The idea would be to break this into multiple small, logically scoped PRs, starting with traits and then layering in initial methods and implementations. I know this would be more time consuming, but in some cases it may be worth it.

Keen to hear your thoughts.

DJMcNab · 2026-01-14T10:51:50Z

Not sure if this is feasible, but would it be possible to extract some of the core logic into multiple, smaller PRs and introduce things iteratively? That could make reviews simpler, reduce cognitive load, and ultimately improve review quality. The idea would be to break this into multiple small, logically scoped PRs, starting with traits and then layering in initial methods and implementations. I know this would be more time consuming, but in some cases it may be worth it.

I think this is viable. The most obvious split is:

Start with PaintScene, Scene and PathSet. This is Implement single-Scene painting for Vello API #1360
Follow-up with Renderer.

I don't think it's easy to have a much smaller scope. This hadn't seemed viable before designing the API, but it does now seem more so.

This is a core part of #1299, split out to be re-viewable separately. One observation which I hadn't properly engaged with until today is that the form proposed in this PR is *independently* useful. That is, useful apps could be made renderer-agnostic with just this API, with none of the "renderer abstraction" pain of #1299. I do think that the renderer API in #1299 does have valuable aspects (having textures be reference counted is still something I really want us to have), but it isn't needed to get something off-the-ground. The core of this PR is two things: 1) The `PaintScene` trait. This is your standard 2d imaging model trait (comparable e.g. with web canvas, [`vello::Scene`](https://docs.rs/vello/latest/vello/struct.Scene.html), [`anyrender::PaintScene`](https://docs.rs/anyrender/latest/anyrender/trait.PaintScene.html)). 2) A renderer-erased implementation of that trait, called `vello_api::Scene`. I call it renderer-erased, because it is (or... will be) invalid to combine renderers within a Scene graph. That's because of image resources and the like. This PR does not have glyph support, and indeed I still believe that Vello API should continue to not have that.

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 7 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

Use peniko::Style instead of newtype redefining it

9d07f90

Stash some more docs

ef95557

DJMcNab added a commit to DJMcNab/vello that referenced this pull request Jan 14, 2026

Import the Scene types and traits from linebender#1299

e948252

DJMcNab mentioned this pull request Jan 14, 2026

Implement single-Scene painting for Vello API #1360

Merged

DJMcNab added a commit to DJMcNab/vello that referenced this pull request Jan 19, 2026

Import the Scene types and traits from linebender#1299

ba638dc

DJMcNab added a commit to DJMcNab/vello that referenced this pull request Jan 20, 2026

Import macro as in linebender#1299

d57e320

DJMcNab mentioned this pull request Jan 20, 2026

Port some tests to the new version of Vello Api #1369

Open

taj-p removed their request for review February 4, 2026 17:18

DJMcNab mentioned this pull request Feb 13, 2026

Vello API: A more sane design for paints #1435

Draft

		// 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?

Comments

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!

grebmeg commented Jan 14, 2026

Uh oh!

DJMcNab commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

DJMcNab commented Nov 21, 2025 •

edited

Loading

DJMcNab Dec 30, 2025 •

edited

Loading

DJMcNab Dec 30, 2025 •

edited

Loading

DJMcNab commented Jan 14, 2026 •

edited

Loading