Module backdrop 

Deciding how many passes a frame’s backdrop-filter layers cost.

A backdrop-filter layer needs, as its input, the pixels behind it. No immediate-mode scene API can express that while the scene is still being built, so the only way to produce one is to stop, render what has been drawn so far, filter it, and carry on. That is a render pass, and passes are the unit of cost this module exists to control.

The naive rule is one pass per filtered layer. Six glass panels would then cost seven passes for a frame that changes nothing between them. The rule here is one pass per backdrop root: panels sitting at the same level, not overlapping each other, all see the same thing behind them, so one snapshot serves all six and the frame costs two passes.

What makes a batch

A batch is a maximal run of backdrop ops that can share one snapshot. An op joins the open batch when the region its filter reads from has not been painted into since the snapshot would have been taken. Anything else - a panel drawn over another panel’s blur region, a stray fill between them, glass stacked on glass - closes the batch and buys another pass.

That last case is deliberate and is an application constraint rather than something to hide in the renderer: glass over glass costs an extra pass, and the counters say so.

Why the planner is separate from any backend

Pass count is decided entirely by the shape of the scene, not by the GPU. A planner that is pure data can be driven by a real document and asked “how many passes?” on a machine with no GPU at all, which is what makes the anti-regression assertion runnable in CI. The backend’s job is to execute a plan, not to decide one.

Structs

BackdropBatch

Backdrop ops that can share one snapshot, and so cost one pass between them.

BackdropOp

One backdrop-filter layer: blur what is behind it, inside clip.

BackdropPlanner

Turns a painted scene’s layer and draw events into a FramePlan.

FramePlan

What one painted frame’s backdrop layers cost.

PlanningScene

A PaintScene that draws nothing and only plans.

Enums

Boundary

Whether a backdrop op could share the open batch’s snapshot.