vello_cpu: Unify render APIs by LaurenzV · Pull Request #1665 · linebender/vello

LaurenzV · 2026-05-23T09:14:32Z

Supersedes #1597, closes #1382.

Motivation

Right now, we have two rendering APIs: render_to_pixmap and composite_to_pixmap_at_offset. We are about to add a third one in #1597. Having this many APIs is very confusing, and after thinking about this more closely I realized that really, what we have been doing is adding methods that do similar things but just with different knobs enabled/disabled. I think it would be much cleaner if we had one single API entry point for rendering to a pixmap, and instead expose the available knobs as a simple settings struct.

Implementation

Therefore, this PR proposes to:

Expose one single render method that can be used to render the contents of a RenderContext into Pixmap-like struct.
Introduce a PixmapMut struct to allow constructing a render target from a mutable borrowed byte slice. Let render always take a PixmapMut, allowing to pass both, a custom buffer or an owned pixmap as the render target.
Introduce a CompositeMode enum that defines whether the contents of a pixmap should be completely replaced (by default), or whether source-over compositing should be used.
Also introduce a PixelFormat struct, to possibly allow Bgra8 in the future, which is useful for MacOS.
RenderMode has been moved from being stored in RenderContext to instead being a setting during rasterization. I initially stored this in RenderContext because I thought it might happen that the setting will also be needed during scene construction, but this turned out to not be the case in the end.
Previously, the implicit assumption was that RenderContext and Pixmap always need to have the same size, although it "accidentally" was possible for them to not have the same size, and some people have made use of that. This PR relaxes the conditions imposed on the size, explicitly allowing size mismatches and also documents what the intended semantics are for each.

Testing

I've added some new tests for the expected behavior. Existing tests pass. I've also ran vello_cpu_winit with the different scenes and didn't notice any regressions.

TODO: I still want to run this version against my PDF test suite, but this shouldn't block a review.

LaurenzV · 2026-05-23T09:21:09Z

@nicoburns If you want to feel free to give it a spin.

nicoburns

I'm onboard with the general concept, but I think it could use some tweaks.

Eventually I would keen on:

Adding PixmapRef
Moving all of the Pixmap types into their own crate (so that things like glifo could use them without depending on `vello_common)

nicoburns · 2026-05-23T10:20:37Z

+    /// Buffer of the pixmap in RGBA8 format.
+    buf: &'a mut [u8],


Probably not blocking, but it's a little weird that Pixmap uses PremulRgba8 whereas PixmapMut uses u8 (my preference would be u8 everywhere).

grebmeg · 2026-05-25T00:42:34Z

+        if settings.composite_mode == CompositeMode::Replace && !target_fully_covered {
+            target.data_mut().fill(0);
+        }


I wouldn’t expect the target would be cleared beforehand when using CompositeMode::Replace. I’d interpret that mode as “replace the rendered region with the scene”, not “wipe everything and then draw the scene”. Also, don’t we already clear regions later with fine.clear? Is Replace equivalent to the Copy blend mode? If so, could we just use the two Porter-Duff operators here and leave it up to the consumer to decide whether the pixmap should be cleared beforehand?

We could change the semantics. It just seems a bit unexpected to me that if the render context is smaller than the pixmap, any pixels that aren’t touched by the scene are left stale (which might also be relevant for our internal use case, in that case we would have to manually clear the pixmap before rendering into it).

Also, don’t we already clear regions later with fine.clear?

We do, but if the scene doesn't cover the whole pixmap, as I mentioned this will leave the outside regions in the existing pixmap untouched. This is why this action is only triggered if !target_fully_covered.

We could change the semantics. It just seems a bit unexpected to me that if the render context is smaller than the pixmap, any pixels that aren’t touched by the scene are left stale (which might also be relevant for our internal use case, in that case we would have to manually clear the pixmap before rendering into it).

Personally, I would expect Replace to behave as a region-local operator: the rendered region overwrites the destination, while pixels outside that region are left untouched. If the caller really wants a whole-buffer wipe, they can do that explicitly on their side with pixmap.data_as_u8_slice_mut().fill(0). That makes the behaviour opt-in, explicit, and preserves the same cost.

There may also be cases where you want to avoid the cost of SrcOver, especially with unpacking wide tile buffers, but still want to replace only the rendered region without clearing the whole buffer, for example when rendering into a preprocessed image, frame, or another existing target.

nicoburns · 2026-06-03T09:52:11Z

I would also ideally like to test this out, but I'm onboard with the API in principle.

LaurenzV · 2026-06-03T10:19:37Z

Anything needed from my side to facilitate this, or do you mean “I’ll test this out once I find the time to do so”?

nicoburns · 2026-06-03T10:21:51Z

I mean “I’ll test this out once I find the time to do so”. I would also be happy for this to land before that if you're confident in it.

LaurenzV · 2026-06-08T11:54:27Z

I agree that the pixmap API should probably be refactored a bit (I'm leaning towards drawing inspiration from tiny-skia here), but I don't want to make this PR harder to review than it already is, so I will leave this for a follow-up.

nicoburns

I definitely have some quibbles with the API, but I've tested this against Blitz and it works fine (no unexpected surprises). So happy for this to land :)

nicoburns · 2026-06-08T13:03:40Z

I agree that the pixmap API should probably be refactored a bit (I'm leaning towards drawing inspiration from tiny-skia here), but I don't want to make this PR harder to review than it already is, so I will leave this for a follow-up.

I'd quite like to see Pixmap/PixmapMut/PixmapRef become it's own mini crate. That could then be used by glifo and could help remove the vello_common dep from glifo.

LaurenzV · 2026-06-08T13:06:20Z

Yeah, as I mentioned, happy to iterate further in a future PR!

(Will still wait for Alex to have had a chance to take a look before merging.)

grebmeg

LGTM

TODO: I still want to run this version against my PDF test suite, but this shouldn't block a review.

Before merging, could you please verify this if you haven’t already?

grebmeg · 2026-06-10T01:35:24Z

+        if settings.composite_mode == CompositeMode::Replace && !target_fully_covered {
+            target.data_mut().fill(0);
+        }


We could change the semantics. It just seems a bit unexpected to me that if the render context is smaller than the pixmap, any pixels that aren’t touched by the scene are left stale (which might also be relevant for our internal use case, in that case we would have to manually clear the pixmap before rendering into it).

Personally, I would expect Replace to behave as a region-local operator: the rendered region overwrites the destination, while pixels outside that region are left untouched. If the caller really wants a whole-buffer wipe, they can do that explicitly on their side with pixmap.data_as_u8_slice_mut().fill(0). That makes the behaviour opt-in, explicit, and preserves the same cost.

There may also be cases where you want to avoid the cost of SrcOver, especially with unpacking wide tile buffers, but still want to replace only the rendered region without clearing the whole buffer, for example when rendering into a preprocessed image, frame, or another existing target.

LaurenzV · 2026-06-10T05:42:50Z

Before merging, could you please verify this if you haven’t already?

Already did yesterday, works fine!

LaurenzV · 2026-06-10T05:57:39Z

Personally, I would expect Replace to behave as a region-local operator: the rendered region overwrites the destination, while pixels outside that region are left untouched. If the caller really wants a whole-buffer wipe, they can do that explicitly on their side with pixmap.data_as_u8_slice_mut().fill(0). That makes the behaviour opt-in, explicit, and preserves the same cost.

Hmm, okay. Let's do it this way: I'll add a TODO for this now to avoid additional churn for #1701, and once that has landed I will try to make that change on top of that. I think it shouldn't be too hard, but I want to avoid making rebasing harder than it needs to be. 😄 I hope that's okay with you.

LaurenzV requested review from grebmeg and nicoburns May 23, 2026 09:20

laurenz-canva force-pushed the laurenz/new_render_api branch from 2846da5 to 5b7d009 Compare May 23, 2026 09:28

nicoburns reviewed May 23, 2026

View reviewed changes

grebmeg reviewed May 25, 2026

View reviewed changes

LaurenzV mentioned this pull request May 25, 2026

Text layout performance regression emilk/egui#8093

Open

laurenz-canva force-pushed the laurenz/new_render_api branch 2 times, most recently from b954db3 to a1237b9 Compare June 1, 2026 04:59

LaurenzV commented Jun 1, 2026

View reviewed changes

Comment thread sparse_strips/vello_cpu/src/render.rs Outdated

laurenz-canva force-pushed the laurenz/new_render_api branch from a1237b9 to bf1b9df Compare June 8, 2026 06:24

LaurenzV mentioned this pull request Jun 8, 2026

vello_cpu: A full rewrite of the frontend #1701

Merged

LaurenzV requested a review from grebmeg June 8, 2026 11:55

laurenz-canva force-pushed the laurenz/new_render_api branch from e6087b3 to 90e5cb5 Compare June 8, 2026 11:59

impl

bd98e50

laurenz-canva force-pushed the laurenz/new_render_api branch from 90e5cb5 to bd98e50 Compare June 8, 2026 12:54

nicoburns approved these changes Jun 8, 2026

View reviewed changes

nicoburns mentioned this pull request Jun 8, 2026

Migrate vello cpu to the new unified API (PixmapMut) DioxusLabs/anyrender#65

Draft

grebmeg reviewed Jun 10, 2026

View reviewed changes

grebmeg approved these changes Jun 10, 2026

View reviewed changes

LaurenzV added 2 commits June 10, 2026 07:45

Add a changelog entry

d199794

Add render and render_with methods

d8a058e

Add a TODO to the changelog

bfff942

LaurenzV added this pull request to the merge queue Jun 10, 2026

Merged via the queue into main with commit 011f4ff Jun 10, 2026
29 of 38 checks passed

LaurenzV deleted the laurenz/new_render_api branch June 10, 2026 07:10

Conversation

LaurenzV commented May 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Implementation

Testing

Uh oh!

LaurenzV commented May 23, 2026

Uh oh!

nicoburns left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nicoburns May 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

grebmeg May 25, 2026

Choose a reason for hiding this comment

Uh oh!

LaurenzV May 25, 2026

Choose a reason for hiding this comment

Uh oh!

LaurenzV May 25, 2026

Choose a reason for hiding this comment

Uh oh!

grebmeg Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nicoburns commented Jun 3, 2026

Uh oh!

LaurenzV commented Jun 3, 2026

Uh oh!

nicoburns commented Jun 3, 2026

Uh oh!

LaurenzV commented Jun 8, 2026

Uh oh!

nicoburns left a comment

Choose a reason for hiding this comment

Uh oh!

nicoburns commented Jun 8, 2026

Uh oh!

LaurenzV commented Jun 8, 2026 • edited by laurenz-canva Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

grebmeg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

grebmeg Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

LaurenzV commented Jun 10, 2026

Uh oh!

LaurenzV commented Jun 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

LaurenzV commented May 23, 2026 •

edited

Loading

LaurenzV commented Jun 8, 2026 •

edited by laurenz-canva

Loading