Module layers 

Opacity layers, retained brackets, and the bracket stack they share with clips.

Three of the display list’s commands open a group — a bracket whose matching pop has to undo exactly what it did, and inside which a hoisted clear is confined (see clear). GroupStack is that one stack. It is deliberately one stack and not three: frust_scene records PopClip, PopLayer and PopRetained as distinct commands, but a widget tree can emit them unbalanced or interleaved, and three stacks would let one kind of pop lift a bracket another kind still relies on. One stack means the innermost open bracket is always what closes, whichever pop closes it.

Opacity layers

A PushLayer at alpha >= 1.0 composites source-over at full opacity, which is precisely what drawing its contents into the parent does — so it lowers to nothing but its rectangle’s clip, exactly as PushClip does (frust_scene documents the two as the same command with alpha fixed). Below full opacity the layer has to be rendered in isolation and composited as a whole, which is a page and a pass in the scheduler (schedule) — so it lowers to a recorded layer plus that same rectangular clip.

The rectangle goes through the clip stack rather than through LayerProps::clip_path: frust lowers every clip to a scissor or a coverage mask and never to an intermediate texture, and the scheduler refuses a recorded layer carrying a clip path for that exact reason. Setting both would clip the layer twice.

Retained brackets

frust_scene states what a renderer that does not retain must do with a PushRetained bracket: paint the body inline, wrapped exactly as if the recorder had emitted push_transform(scale_about(scale, rect.center())) when scale != 1.0 and push_layer(rect, alpha) when alpha < 1.0. RetainedStack is that emulation, and it is also the whole of what a compiler with retention off does (see SceneCompiler::set_retained_layers).

A compiler with retention on lowers the outermost bracket the same way and additionally records it as a RetainedBracket: the body becomes a recorded layer of its own whatever its alpha — at full opacity one with no clip of its own (GroupStack::push_retained), so the inline lowering’s geometry is unchanged — which the renderer’s retained-page store (crate::cache::retained) either admits, rendering the layer into a page it keeps across frames, or refuses, in which case the scheduler serves it as the ordinary layer the inline emulation describes. A DrawRetained becomes an empty recorded layer standing at its painter-order position, which the store resolves to a composite of the resident page. The page holds the body with the presentation scale baked in, exactly as the inline lowering rasterizes it, and without the alpha, so a page is reusable under any alpha and any whole-pixel move of the same transform (RetainedPlacement).

The scale is applied as a correction composed ahead of every subsequent command’s own transform rather than by rewriting the body’s commands, because the body was recorded in the ordinary composed transform space: the bracket’s presentation parameters are deliberately not baked into it. The correction that reproduces push_transform around a body already carrying transform is transform * scale_about(..) * transform.inverse() — see retained_correction.

Only the outermost bracket is honoured, which the display list explicitly permits: an inner bracket’s own alpha and scale are ignored, and its depth is tracked only so the matching pop can be identified. With retention on, an inner bracket’s key — and that of any bracket that records no RetainedBracket — is listed in CompiledFrame::retained_superseded instead: its body is painted as part of the outermost one, so whatever page the key held is older than this frame’s recording and the store evicts it.

Structs

Group

One open bracket: what its matching pop has to undo, and the device-space bounds a clear hoisted past it is confined to.

GroupStack

The compiler’s stack of open clip, layer and retained brackets.

RetainedBracket

One retained bracket a compiler with retention on recorded this frame, for the renderer’s store (crate::cache::retained) to resolve.

RetainedPlacement

Where a retained body lands on the device grid: the composed transform its local coordinates are mapped through, split into the linear part and the translation.

RetainedStack

The retained bracket’s inline emulation: how deep the walk is inside one, and what the outermost bracket installed.

Enums

LayerLowering

How a PushLayer bracket lowers.

RetainedKind

The two retained commands, as the store needs to see them.

Functions

layer_props

The recorded properties an isolated opacity layer carries.

lower_layer

How a layer at alpha lowers.

retained_correction

The correction that reproduces a retained bracket’s presentation scale.