Visual layer plan by waywardmonkeys · Pull Request #1723 · linebender/xilem

waywardmonkeys · 2026-04-12T11:32:57Z

This PR introduces VisualLayerPlan as Masonry’s shared visual-layer model and uses it to carry explicit paint boundaries from masonry_core through host presentation.

The main outcome is that Masonry can now represent and preserve an ordered layer sequence like:

Masonry scene content below
a host-managed external surface slot
Masonry scene content above

That gives us a cleaner path toward compositor-driven presentation, instead of flattening everything into one scene and treating external content as a special case.

This PR does not claim that the compositor model is finished.

In particular:

VisualLayerPlan is still a flat ordered plan, not a grouped/tree compositor model
the subduction path is an early host integration, not the final cross-platform presentation architecture
scene-layer caching / frame pacing / platform-native presenter choices re follow-up work

waywardmonkeys · 2026-04-12T14:21:27Z

This was done with assistance from Codex (gpt-5.4, high). But the overall design is mine. (But probably still evolving ...)

PoignardAzur

I'm going to be honest, I gave up halfway through subduction_presenter.rs, because at some point I don't even know if I'm giving feedback to Bruce or to some LLM, and this doesn't feel like a good use of my time.

Anyway, the guiding principle of Masonry is that we make a lot of effort to keep the code readable for complete beginners. This principle is relaxed for Masonry Winit because platform glue code is inherently messy, but even then, this PR does not remotely meet our standards.

PoignardAzur · 2026-04-12T14:15:39Z

Let's keep all the examples in masonry/examples/.

This one is here for now because parts of it are very specific to masonry_winit and with other stuff that I had locally, it was annoying to keep other things building ... but I'll move it before this lands.

PoignardAzur · 2026-04-12T14:49:18Z

This test file should be moved to masonry/src/tests/.

There's a few reasons we do a lot of tests in masonry instead of masonry_core. The main one is that masonry defines a lot of widgets that are useful for tests. For instance, PaintLeaf, TripleRow, OffsetBox and MixedTripleRow could trivially be replaced by SizedBox and Flex.

Overall, tests are supposed to be a kind of maintainer-only documentation explaining what we expect from the code. You shouldn't need to read the implementation of four custom widgets to get to read a test.

If we didn't have to implement a bunch of empty methods for every widget, this would've been a lot easier as well.

But the things that it is testing aren't as easily done with SizedBox / Flex given that they make things less easily deterministic ..

But I'll move it after other things are resolved.

PoignardAzur · 2026-04-12T14:51:05Z

+#[cfg(not(target_arch = "wasm32"))]
 use std::fs::File;
+#[cfg(not(target_arch = "wasm32"))]
 use std::time::UNIX_EPOCH;


These seem like drive-by changes? I don't think they're needed for this PR.

They were required to fix CI since with this, some stuff started getting compiled for Wasm in the existing CI that wasn't happening before.

They can probably be done in a separate PR at some point.

PoignardAzur · 2026-04-12T14:58:38Z

Alright, so this file defines breathes in VisualLayerId, ExternalLayerKind, VisualLayerBoundary, VisualLayerKind, VisualLayer, SceneVisualLayer, ExternalVisualLayer, and VisualLayerPlan.

This is my problem with these AI-generated PRs. Even if all of the code is correct, they add a lot of API surface that you then need to learn and maintain.

Also, general comment: while this isn't documented anywhere (but it should be!), Masonry modules usually adhere to a coding style where all types are defined first, then implementations. This helps identify which types are composed of which other types, etc.

Some of the are because I used to have support for actual child windows on Windows and macOS before, not just a single external layer. I've removed that though thinking I might add it back, but realistically, I'll probably never actually re-implement that within Masonry.

The problem here with these types isn't that it was AI generated, it is that at various points (over the last more than a week), this PR has been doing a lot of other things along the way that I removed.

Also, some parts of this are actually complex things to model and require some detail.

But the VisualLayerPlan is the actually important thing here and where most of the attention has gone.

PoignardAzur · 2026-04-12T15:03:35Z

+    /// Where this visual layer boundary originated.
+    pub boundary: VisualLayerBoundary,


We've had a discussion about AI-generated doc lately, where Raph posted a parody of AI doc. Reading a lot of doc in this file reminds me of Raph's parody; this line is a good example.

When we have a type named VisualLayer with a field named boundary of type VisualLayerBoundary, a doc that says "Its the visual layer boundary" is extremely unhelpful.

Would you rather the type be called Boundary?

It is fair to call out that the doc comment could use more work.

Or I guess we could mock the work that I'm doing instead of something productive.

PoignardAzur · 2026-04-12T17:07:42Z

+    fn on_visual_layers(
+        &mut self,
+        window_id: WindowId,
+        ctx: &mut DriverCtx<'_, '_>,
+        layers: &VisualLayerPlan,
+    ) {


I'm not super clear on how this is supposed to be used, from reading documentation.

Is the expectation that apps with custom layers will render them to wgpu from this method? Or just update them?

Also, on_visual_layers is a confusing name.

It is for letting a host inspect the frame without taking over presentation. I'll just remove it.

PoignardAzur · 2026-04-12T17:14:21Z

+pub trait SceneLayerRenderer {
+    /// Render the given scene layer into `target.view`.
+    fn render_scene_layer(
+        &mut self,
+        target: SceneLayerTarget<'_>,
+        layer: SceneVisualLayer<'_>,
+    ) -> Result<(), BoxError>;
+}
+
+/// Realize host-owned external layers into the textures allocated by the subduction presenter.
+pub trait ExternalLayerRenderer {


I think at some point I'm going to put out an official moratorium on adding more traits to the Xilem codebase, because the trait inflation is getting way out of control.

I'm pretty sure these two could just be impl Fns.

PoignardAzur · 2026-04-12T17:16:18Z

+pub struct SceneLayerTarget<'a> {
+    /// Device used for rendering.
+    pub device: &'a wgpu::Device,
+    /// Queue used for uploads and submission.
+    pub queue: &'a wgpu::Queue,
+    /// Texture view owned by the compositor for this layer.
+    pub view: &'a wgpu::TextureView,
+    /// Output size in physical pixels.
+    pub output_size: winit::dpi::PhysicalSize<u32>,
+    /// Window scale factor used to convert logical layer geometry into pixels.
+    pub scale_factor: f64,
+}


Okay, so this struct is exactly the same as ExternalLayerTarget, except without the format field. I suspect they could have been merged.

PoignardAzur · 2026-04-12T17:17:31Z

+/// Host-specific renderer for external layers with optional per-layer state.
+pub trait ManagedExternalLayerRenderer {


Oh hey, a third trait!

PoignardAzur · 2026-04-12T17:17:57Z

+    layer: Layer,
+}
+
+trait ExternalLayerStateDriver<Layer, State> {


Oh hey, a fourth trait!

waywardmonkeys · 2026-04-12T19:58:10Z

I'm going to be honest, I gave up halfway through subduction_presenter.rs, because at some point I don't even know if I'm giving feedback to Bruce or to some LLM, and this doesn't feel like a good use of my time.

It is fair to give up in parts of that version of the presenter. I've done a massive simplification on it now that I've removed some other things and will probably never re-implement them within Masonry (like OS child windows and a form of native control integration).

waywardmonkeys force-pushed the visual-layer-plan branch 4 times, most recently from 7625468 to 8f61dd7 Compare April 12, 2026 14:19

PoignardAzur requested changes Apr 12, 2026

View reviewed changes

waywardmonkeys added 3 commits April 13, 2026 03:39

Introduce VisualLayerPlan and paint boundaries

8bd7d12

Add an ExternalSurface widget slot

5b31a43

Add subduction presentation support to masonry_winit

1d58c2b

waywardmonkeys force-pushed the visual-layer-plan branch from 8f61dd7 to 1d58c2b Compare April 12, 2026 20:40

waywardmonkeys marked this pull request as draft April 12, 2026 20:49

waywardmonkeys mentioned this pull request Apr 13, 2026

Fix wasm-target hygiene in masonry_core #1731

Merged

		/// Where this visual layer boundary originated.
		pub boundary: VisualLayerBoundary,

		/// Host-specific renderer for external layers with optional per-layer state.
		pub trait ManagedExternalLayerRenderer {

Conversation

waywardmonkeys commented Apr 12, 2026

Uh oh!

waywardmonkeys commented Apr 12, 2026

Uh oh!

PoignardAzur left a comment

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!

Choose a reason for hiding this comment

Uh oh!

PoignardAzur Apr 12, 2026 • 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!

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!

waywardmonkeys commented Apr 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

PoignardAzur Apr 12, 2026 •

edited

Loading