Blur
lurq has two blurs, and they answer different questions:
| Modifier | What is blurred | CSS counterpart | Typical use |
|---|---|---|---|
.blur(radius) | The element and everything inside it | filter: blur() | A panel going out of focus, a placeholder, a transition |
.backdrop_blur(radius) | What is painted behind the element, inside its box | backdrop-filter: blur() | Frosted glass: toolbars, sheets, a scrim under a modal |
Both work on every node and component, on the wgpu renderer and the native DX12 one, and need no feature flag.
The Radius
Section titled “The Radius”radius is in logical pixels and means what a shadow’s blur radius means: the Gaussian’s standard deviation is half of
it. blur(8.0) softens an edge as BoxShadow::new(0.0, 0.0, 8.0, ..) softens a shadow’s, and as the canvas’s
Filter::Blur(8.0) does.
- CSS’s
blur(4px)names the deviation itself, so it isblur(8.0)here. A design tool’s layer blur of 8 isblur(8.0). 0(the default) is no blur, and costs nothing: no layer, no extra pass.- The radius is clamped to
layout::opacity_layer::MAX_BLUR_RADIUS(256). Negative and non-finite radii are no blur. - The radius is in the element’s own units. Under a
.transform(...)that scales the element, its own or an ancestor’s, the blur scales with it:blur(8.0)on an element scaled by 2 looks likeblur(16.0)unscaled. A transform that scales the two axes differently blurs by their geometric mean, the same along both.
Blurring An Element
Section titled “Blurring An Element”.blur(radius) paints the element’s subtree into an offscreen layer and draws the layer through a Gaussian blur. What
is behind the element is not touched.
use lurq::{animation::Transition, components::{Column, Text}};
// A panel that goes out of focus when `inactive`, over 200 ms.Column::new() .padding(16.0) .background("#ffffff") .child(Text::new("Drafts")) .blur(if inactive { 6.0 } else { 0.0 }) .transition(Transition::blur().duration_ms(200))- The blur spreads past the element’s box by three deviations, which is
1.5 * radius. The element’s layout box does not change: neighbours do not move, and the spread paints over them. - Containers clip by default, so a blur is cut at its parent’s edge like any child that paints outside its parent.
Give it room with padding, or call
.overflow_visible()on the containers it should escape. - Where the element is cut by a clip or by the window’s edge, the part of it just past the cut still bleeds into what shows. A blurred element scrolled half out of a list, or a blurred page that fills the window, does not fade out along the cut. A rounded clip cuts the blur with its corners.
.blur(...)and.opacity(...)on one element share a layer: the blurred result is faded.- Blur changes painting only. Layout, scrolling and hit testing are the same at any radius: a blurred button still takes clicks.
Frosted Glass
Section titled “Frosted Glass”.backdrop_blur(radius) blurs what is already painted behind the element, inside the element’s box, and the element
then paints itself over the result. The blur shows wherever the element is translucent, so give it a translucent
background; an opaque one hides it. Under an opaque background of one color, with the element at full opacity, the
frame does not blur at all: only the half-covered pixels along the box’s edge show what is behind it, and they show it
sharp.
use lurq::components::{Column, Text};
// A glass toolbar over whatever scrolls under it.Column::new() .padding(12.0) .background("#ffffff40") .border_inside(1.0, "#ffffff99") .rounded(12.0) .backdrop_blur(16.0) .child(Text::new("Toolbar"))- The blur fills the element’s box with its corner radii and does not spread past it. It is cut by the clips the element is under, their rounded corners included.
- Under a
.transform(...)the blur fills the transformed box: turned, scaled or skewed as the element is. - At the window’s edge the blur reads the edge pixels as if they went on, so glass against an edge does not darken there.
- The element’s own
.opacity(...)fades the blur with it: at0.5the blurred backdrop is mixed half and half with the sharp one. Transition::backdrop_blur()animates the radius.
What Counts As Behind
Section titled “What Counts As Behind”“Behind” is everything painted before the element: earlier siblings, the backgrounds of its ancestors, the page under an overlay. Content painted after the element, its own children included, is painted over the glass and stays sharp.
Inside an ancestor with .opacity(...) below 1 or a .blur(...), behind is only what that ancestor has painted so far,
as in CSS: the ancestor is drawn into a layer of its own, and the glass does not see through the layer to the window.
A glass panel that is the only thing inside a faded wrapper therefore blurs nothing. Put the opacity on the glass
element itself, or keep the content it should blur inside the same wrapper.
Glass Side By Side
Section titled “Glass Side By Side”Each backdrop blur reads what is behind it at its own place in the frame, so glass that stands close together (a column
of round buttons over a video) blurs the same pixels over and over, and each next one shows the ones before it, blurred,
at its edge. .backdrop_group(key) blurs the backdrops of the same key and radius in one window or layer as one: the
first of them reads what is behind all of their boxes, and the others show what it read, each in its own box.
use lurq::components::Row;
let button = |key: &str| { Row::new() .size(44.0, 44.0) .rounded(22.0) .background("#ffffff24") .backdrop_blur(20.0) .backdrop_group(key)};// Five buttons cost one copy and one blur in a frame where what is behind them moves, not five.- A glass of the group does not show the glass before it behind it, as it would alone; it shows what was behind the first.
- The key is any
Hashvalue. Glass of one key that stands apart (two columns of buttons on two pages a pager shows at once) is still blurred as one, over the rectangle that holds them all: give each column its own key. - The DX12 renderer blurs each backdrop of a group on its own.
Animating
Section titled “Animating”Both radii animate like any other style value, in transitions and in keyframe animations:
| Transition | Property |
|---|---|
Transition::blur() | AnimatableProperty::Blur |
Transition::backdrop_blur() | AnimatableProperty::BackdropBlur |
Transition::all() | Both, with everything else |
Like opacity, an animating blur changes painting only: the element keeps its layout cache while the radius runs, so a blur transition lays nothing out again.
.blur(...): the cost follows the layer’s pixels, not the radius. A wide blur runs on a reduced copy of the layer, soblur(64.0)is not slower thanblur(8.0). A blurred layer takes three or four pooled textures for its frame and is painted for1.5 * radiusmore on each side than it shows, which is what the radius limit bounds. The wgpu renderer keeps the blurred pixels, and a frame in which the layer holds what it held and stands where it stood composites them again with one draw: the layer is not painted, nor blurred (see When A Layer Is Blurred Again). A blurred picture under a playing video, or under anything else that moves, costs that one draw a frame..backdrop_blur(...): a frame that blurs a backdrop stops the frame’s drawing, copies the pixels around the box and blurs the copy. That is a few passes and pooled textures of about the box’s size. The blurred pixels are then kept, and a frame in which the same pixels are behind the glass puts them back with two draws: no copy, no pass, no texture taken (see When A Backdrop Is Blurred Again). Glass over a backdrop that holds still costs next to nothing, however much of the window it covers; glass over something that moves is blurred in every frame it moves. A long list in which every row is glass is not what it is for: blur the list’s backdrop once with one element instead. Glass that stands close together is blurred as one with.backdrop_group(...)(see Glass Side By Side), and glass under an opaque background is not blurred.- Textures are pooled and reused across frames, and released after a while without use. A frame without blurs creates none.
When A Backdrop Is Blurred Again
Section titled “When A Backdrop Is Blurred Again”The wgpu and the DX12 renderer keep the blurred pixels of a backdrop blur and put them back in the frames that follow, for as long as the blur reads the same pixels. They tell that from what the frame draws, never from the pixels themselves. A kept blur is put back while all of this is what it was in the frame that blurred it:
- The rectangle of pixels the blur reads: the element’s box inside the clips it is under, and about
1.5 * radiusaround it, in physical pixels. So the element’s place and size, its radius and the window’s scale. - What those pixels are in: the window, with its size and clear colour; or, for glass inside an ancestor with
.opacity(...)below 1 or a.blur(...), the rectangle that ancestor’s layer is painted for. - Everything painted before the element that can reach the rectangle, in the order it is painted: every fill, border, shadow, glyph, image and SVG, each with its place and size, colours, gradient, corner radii, transform and clip. A glyph is its place in the glyph atlas, with the atlas’s version and size; an image its id, frame and version; an SVG its mesh.
- Every faded or blurred group that shows inside the rectangle, with everything painted into it.
- Every other backdrop blur under this one that changes pixels inside the rectangle, with everything it reads in turn.
It is blurred again in a frame where any of that differs: something behind the glass changes colour, moves, appears or goes, the glass moves or changes size or radius, the window is resized. An animation behind the glass blurs it in every frame of the animation, and not after.
Some pixels change without anything the frame draws changing: a video frame or a camera image in a native texture,
a Canvas, an external wgpu texture. Glass that can reach one of those is blurred in every frame,
and nothing is kept for it. An image whose pixels come from memory is told by its version, so a GIF or a decoded
video frame behind glass blurs it when a new frame is shown.
These do not blur it again:
- The element’s own
.opacity(...), its corner radii and the corners of the clip it is under. They are applied as the blur is put back, so glass that fades in over a still backdrop is blurred once. - Anything painted after the element: its own content and children, and whatever lies over it.
- Anything that cannot reach the rectangle, however it changes; and elements added or removed elsewhere, since the order things are painted in is compared, not their numbers.
A new glyph anywhere changes the atlas, which blurs glass with text behind it once.
The kept pixels are those of the blur’s own passes: a wide blur keeps its reduced copy, a quarter of the rectangle’s
pixels or less from backdrop_blur(32.0) at scale 1 on. A window keeps at most 64 blurs, in textures of at most
twice the bytes of its own pixels (1 MiB for a small window); a blur past that is not kept and runs every frame. So
does a blur with so much painted behind it that writing those draws down takes more than 1 MiB. A kept texture goes
back to the pool when its glass is gone, has moved or changed size, and when the window is resized.
A custom RenderEngine keeps what it chooses to: the RenderList of a frame says nothing about the frame before.
When A Layer Is Blurred Again
Section titled “When A Layer Is Blurred Again”The wgpu renderer keeps the blurred pixels of an element with .blur(...) the same way, and composites them in the
frames that follow without painting the element or blurring it, for as long as the element holds what it held. A kept
layer is put back while all of this is what it was in the frame that blurred it:
- The rectangle the layer is painted for, and the blur’s radius and rectangle, in physical pixels: so its place and size, its radius and the window’s scale.
- Everything painted into the layer, in the order it is painted, as for a faded or blurred group behind glass above:
every fill, border, shadow, glyph, image and SVG with all it is drawn from, the groups inside it, and its
.opacity(...)and clips.
It is painted and blurred again in a frame where any of that differs: a picture in it loads or changes its version,
it moves (a page that slides blurs it in every frame of the slide, and not after), it fades. What lies under it or
over it changes nothing. A layer that holds a video frame, a camera image, a Canvas or an external texture is
blurred in every frame, and so is one with a .backdrop_blur(...) inside it, which reads what the same frame paints.
The kept textures are counted as a backdrop blur’s are, apart from them: at most 64, in at most twice the bytes of the
window’s pixels. The DX12 renderer paints and blurs a blurred layer in every frame.
Checking The Result
Section titled “Checking The Result”- A devtools node screenshot draws both blurs on the CPU. Its capture is the node’s own size, so what lies outside it does not bleed in at the capture’s edges.
lurq_screenshotover MCP and frame captures read the rendered frame back, blurs included.cargo run -p lurq --example layer_blur_capture_check --features screenshot,wgpu,dx12renders a scene of blurred nodes and glass through both renderers and compares the captures.cargo run -p lurq --release --example backdrop_blur_probe --features screenshot,wgpu,dx12,perf_profilemeasures the frames of a window of glass on both renderers, at several radii and scales: the CPU phases, wgpu’s GPU time, and how many backdrops each frame blurred and how many it put back from a kept result.
For Render Engines
Section titled “For Render Engines”A custom RenderEngine sees the blurs in the RenderList:
- A blurred element is a
LayerCmdwithblur: Some(LayerBlur).LayerBlurhas the deviation in physical pixels, the rectangle the layer’s content is painted for (LayerCmd::painted(); larger than theboundsit shows in, and possibly reaching outside the window), and the rounded clip to cut the result to, if the element is under one. - A backdrop blur is a
BackdropCmdinRenderList::backdrops: the box, its radii, transform and clip, the deviation in physical pixels, the render order it happens at, and the key of the group it is blurred with, if any. No draw has that order: the blur comes after every draw of a lower order and before every draw of a higher one, in the target those draws are in. RoundedBox(layout::opacity_layer) describes a rounded box that may be turned or scaled, with its bounds and its coverage of a pixel.
An engine that ignores LayerCmd::blur draws the layer unblurred, and one that ignores RenderList::backdrops draws
the frame without its glass.