Module backdrop 

The blurred material floating chrome is made of.

Floating chrome — the palette, menus, popovers, quick settings, sheets, notifications and chrome over media — is drawn over a blurred copy of what is behind it, tinted with the panel ground (docs/design-language.md, “Material and transparency”). The blur radius and the tint’s opacity are theme roles (surfaces.material_blur_px, surfaces.material_opacity, set by the theme document’s material); a surface asks for the material with crate::floating_surface::Material::Floating, and nothing outside the theme and this module picks a blur radius or a tint.

Vello cannot sample what it has already drawn, so the blur is a pass that runs before the frame:

1. While a host holds a BackdropRecording, fill draws a surface’s body as a placeholder image under the tint and records what lies behind it: what the scene held so far, which of the host’s scenes that is (layer_scene), the surface’s bounds and its blur radius.
2. The host turns those records into a BackdropFrame in its target’s pixel space, each region carrying the complete scene composed below the surface.
3. A renderer that composites materials calls BackdropBlur::prepare: each region’s backdrop is rendered at half resolution, halved until the blur fits a short kernel, blurred separably and substituted for the placeholder; BackdropBlur::release drops the substitutions.

The placeholder’s own pixels are the opaque panel ground, so any path that does not substitute it (no blur pass, a failed backdrop render, a capture of the scene) shows the opaque material — as do reduced transparency, forced colours and a theme without blur.

Modules

desktop

The desktop, blurred, for surfaces that stand on it alone.

Structs

BackdropBlur

The GPU half of the material: renders, blurs and substitutes each region’s backdrop on one device. Built once per renderer.

BackdropFrame

The backdrops one frame draws its floating surfaces over.

BackdropRecording

Records the surfaces drawn in the blurred material on this thread until Self::finish. Nests: an inner recording hides the outer one and restores it when it ends.

BackdropRegion

One surface’s backdrop, in the pixel space of the target it renders to.

BackdropStats

What BackdropBlur::prepare did, for frame profiling.

Legible

The luminance range what shows through a translucent surface is compressed into, so ink chosen against the surface’s ground stays legible over anything below it: the material’s band (material_band) as relative luminances. The backdrop pass maps what it sampled into it (Self::tone is the same arithmetic): luminance is compressed evenly in contrast (a contrast ratio below becomes a smaller, fixed power of itself), and each colour keeps its hue: dimmed, its channels scale with its luminance; lifted, it keeps how far its channels stand off its grey, so a near-grey stays near-grey. A bright photo shows dimmed but in its own colours and shapes, a dark page lifted without a cast, never as one flat colour.

RecordedBackdrop

One surface drawn in the blurred material while a recording was active, in the recording’s coordinates.

Refraction

How a region’s backdrop is bent, in the pixels of the space it is recorded or drawn in: a convex lens along the rim of a rounded rect. Within band of the outline each pixel shows what lies below a point moved toward the inside along the outline’s normal, by strength at the outline easing quadratically to none at the band’s inner side; the rest shows what lies below straight. The backdrop pass evaluates it together with the blur (Self::displacement is the same arithmetic), so a bent surface costs no more to draw than a blurred one and a settled one draws nothing new.

Sample

What a backdrop brush asks of the pass: how blurred, through what lens, at what corner radius.

Enums

Sampling

How a backdrop sample is filtered.

Constants

MATERIAL_SPREAD

How far, as a contrast ratio, a translucent surface may stand off its ground anywhere, whatever is behind it. Every ink drawn on a surface is chosen to clear 7:1 on the opaque ground (SMALL_TEXT_MIN_CONTRAST; a disabled row’s dim ink included), so on the material it still clears 7 / 1.5 ≈ 4.7:1, above body text’s 4.5:1 with room for 8-bit rounding.

MAX_BACKDROP_REGIONS

Most surfaces one frame blurs behind. Later ones in the same frame are opaque: each region costs one extra render of everything below it.

Functions

append_nested

scene.append(child, Some(transform)), carrying the floating surfaces drawn into child since nest_scene onto scene: what scene holds so far lies below them. Returns how many surfaces child carried. A cache that carried any must be redrawn on every recorded frame: reused, its surfaces would show the opaque material.

backdrop_texels

The size in texels of the image a surface with bounds (recording pixels) is drawn with: what a provided backdrop must measure. cell_px is the cell the surface shows as pixels (Sampling::Blocky), in the same recording pixels, or 0 for a smoothly sampled surface.

fill_role

Fill shape as a surface of role stands: its finish’s painter set (Theme::painter) draws it over ground. A floating or bar surface under an active BackdropRecording can show what lies below it, held in the material’s band, bent and lit as its set says; every other surface, and any without a backdrop pass, is drawn opaque.

fill_role_flush

fill_role for a surface whose flush sides stand on the display’s own edge: it draws no edge, rim or hairline there, so no pixel of another colour shows between it and the screen’s edge. Every other side keeps what its material gives it.

forget_nested

Forget the floating surfaces drawn into child since nest_scene: it is about to be drawn again. A no-op outside a recording.

layer_scene

Floating surfaces drawn into scene sit on layer. The host names every scene it draws its frame into, so it can rebuild what lies below a surface: the scenes it composes under that layer, plus RecordedBackdrop::below. A host drawing one scene names it once.

material_band

The darkest and the lightest colour the floating material shows over ground: the ground stepped toward each end of the theme’s neutral ramp until it stands MATERIAL_SPREAD off it (or reaches the end).

nest_scene

child is a scene a widget draws now and composes into another scene afterwards with append_nested (a subtree cache). Floating surfaces drawn into it wait there and take what lies below them once it is appended. child must not move until then. A no-op outside a recording.

provide_backdrops

Hand the next frames the blurred backdrops of their surfaces, by region slot of the outermost recording: a host that cannot blur in its renderer (an app rasterized on the CPU inside a compositor, which holds what lies below) has them made where that is known and drawn in place of the placeholders, so the material’s band and tint apply to them as to a substituted blur. An image is used only while its size is the slot’s placeholder size (backdrop_texels); the rest stay opaque.