Liquid Glass UI

-unity-material accepts USS-authored prop() values, but the shader also needs the element’s laid-out size, which USS cannot know. The two cannot be mixed: MaterialDefinition is a struct whose property list is a shared List reference with an internal deep-copy constructor, so reading the USS-resolved value and adding a size to it would mutate the shared computed style of every element resolving the same rule.

LiquidGlassContentSurface therefore builds the whole definition itself, from the --glass-* custom properties plus the size, and writes it inline. Custom properties also cascade one at a time, unlike prop(), where a :hover variant would have to restate the entire declaration at every site.

Transitions still come for free — an inline write is a computed-value change like any other, so transition-property: -unity-material makes UI Toolkit interpolate the properties itself. Two consequences worth knowing:

These are not style preferences — each one covers a failure that is otherwise silent.

Corner radii come from the resolved border-radius automatically, rendered as superellipse (squircle) corners that degrade to exactly circular where the radius fills the shape — so circles and capsule ends stay round while panel corners get the iOS-like fatter curve. Because the silhouette no longer depends on UI Toolkit’s tessellation, the element may carry whatever radius its content shaping wants.

-unity-material transitions, and every glass parameter rides inside it, so a :hover tint eases rather than snapping — provided the element declares the transition:

That declaration lives on the shared pressable and circle-button classes (see Press feedback), which is the practical reason to give tappable glass one of them: an element that declares no transition changes tint instantly. transition-timing-function is honoured, unlike under the old hand-rolled ramp.

opacity is the one property glass does not take at face value — see Fading with opacity.

A few writes deliberately snap instead of easing: those that change what the glass reads rather than how it looks — the dynamic backdrop texture, the pyramid parameters, and the body mode. All three are enumerations or descriptions of a texture’s state with no meaningful half-way point, and ValuesMaterialDefinition.LerpPropertyValues keeps the old texture until t = 0.5, so interpolating one of them reads as a black flash rather than as an in-between.

The scope’s backdrop rect — an element’s window into its pyramid — snaps for a different reason. Easing it slides the backdrop across the element rather than letting the element travel across a backdrop that holds still, which is the one thing the mapping is for. It lags by the transition duration, so the further the element travels the worse it reads: a glass button in a sidebar sliding in from the screen edge drags its backdrop along and catches up afterwards. A jump and a continuous move want the same answer here, so no distinction is drawn between them.

What the snap still costs is narrow: a tint or blur ramp beginning on a frame the element also moves arrives at once instead of easing, since both ride the one material. Which gives the authoring rule — settle the position first, animate second. OptionPicker is the worked example: it writes its placement on one layout pass and only adds the class that reveals it on the next, so the ramp starts from a rect that has stopped changing.

Addressing the pyramid in screen space, the way --glass-background-global addresses the scene copy, would take the element’s position out of the material altogether and with it the whole of this — at the cost of extending the unverified SV_POSITION orientation ground to dynamic glass as well.

Glass does not dim uniformly when it fades. Dimming a real pane is not what disappearing looks like: what goes is the optics, and what reads is the pane losing its lensing and its rim, and its content clearing off it, before it loses itself. So opacity is reshaped for the whole app — every part of a glass element leaves on its own power curve:

Read against the fade’s progress rather than the opacity, that curve is 1 - (1 - t)^k: it leaves at a finite rate — an exponent below 1 would take the children to half gone on the first frame of a fade, which reads as a pop rather than a start — and eases to a stop as it vanishes.

Two things ride along with the body rather than on a curve of their own: the refraction thickness and both blur radii drain linearly to zero, so the glass flattens into its own body colour and lets its backdrop go sharp instead of dissolving as glass; and the silhouette swells by FadeScale (4%), scaled about the element’s centre.

It is the effective opacity — element × ancestors — so fading a container that holds glass does all of this to the glass inside it, which is how popups and dialogs get it.

The two basic-glass texture sources are not interchangeable — they differ in how the texture is addressed and how hard it is refracted.

--glass-background (and SetBackground) is element art: stretched over the element’s own box, moving with it, and refracted at LIQUID_GLASS_IMAGE_REFRACTION_SCALE (10%) of the tuned strength. At full strength the rim lensing of element-sized art throws most of the image off its own edges, which reads as distortion rather than glass.

--glass-background-global is a backdrop the element sits in front of: sampled in screen space through SV_POSITION, so the texture holds still while the element moves across it — under scrolling and transforms alike, with no per-element panel rect and no per-frame position poll — and refracted in full. The shader knows one such name, _LiquidGlassSceneColor; anything else is reported and ignored.

It blurs, at --glass-blur like everything else. The scene copy carries its own chain, built once per frame by LiquidGlassSceneColorPass and read through the same radius → lod mapping a scope’s pyramid uses — one chain for the whole screen, since every element sampling it wants the same scene. How deep that chain goes is the feature’s Scene Blur Levels, which is therefore the ceiling on what a screen-space body can blur by; at 0 there is no chain and every read lands on the sharp copy. The feature’s Scene Backdrop switch drops the copy and its chain together — see Turning the scene backdrop off.

What that buys, and what it does not: the scene really does bend through the bevel and shift as the element moves, blurred, for the cost of one batch break. But it is the scene only — never other UI — and it is one frame old. Frosted glass over live UI is what glass-dynamic is for; this is the cheap option for elements that only ever wanted the scene behind them.

Elements added from C# after the reload scan (or that gain the class at runtime) are not picked up automatically — register them explicitly, and unregister when they leave:

Unregister is safe to call late — after the element has left its panel, or after UI Toolkit has thrown the whole tree away on an editor UI reload. A reload does not merely detach the old tree: it releases every element in it (VisualElement.Clear(RecursiveReleaseResources)), which recycles their layout nodes to the elements of the tree that replaced them. Styling such an element would therefore either throw inside UI Toolkit or land on somebody else’s element, so Unregister skips the material clear for an element that is no longer in a panel — nothing off-panel draws, so there is nothing to clear. A caller holding surfaces across reloads (a controller with a list of runtime cards) can drop them whenever it next rebuilds; it does not have to catch the tree going away.

Which variant you get is the element’s class list, exactly as in UXML — there is one entrance for both. An element carrying glass-dynamic is additionally given a scope of its own, handed to the tracker’s per-frame tick, and Unregister releases that along with the surface. So a runtime overlay that should frost the screen it opened over — a dropdown list, a menu — needs nothing at the call site beyond the class it would carry anyway. `OptionPicker’s list is the worked example.

A scope to itself is the correct grouping for such an element rather than a fallback. A scope places its snapshot in front of its first participant, so an overlay appearing over a finished screen needs a snapshot taken after that screen is drawn — which no scope rooted further up can give it, and which is C2. With one participant C1 holds by construction too. Both clauses come free here; neither does for glass authored in UXML, which shares its panel’s scope with everything else in it.

Not every runtime element escapes the scanned tree, though — BetterScrollView’s edge arrows are built into a scroll view that sits inside a screen root — and a scan reaching one of those would be the second surface the warning above is about. `ScanRoot therefore never registers a second surface on an element Find already answers for: a surface from the panel’s own previous scan it takes back, and anything else was registered from C# and has an owner. Leaving that one alone is what keeps its own scope, and with it the backdrop its position actually calls for.

The scan is not a one-time event to be reasoned around, which is what makes this load-bearing rather than defensive. RegisterUIReloadCallback fires straight away when the tree is already built, and RefreshPanels runs from the manager’s OnEnable and on every scene load, so a tree that has been up for a while is rescanned routinely. Without the check, a runtime element registered inside it worked until the first rescan and then had two surfaces — both generating a quad, both writing the material, the scan’s one grouped into the panel scope and holding no backdrop of its own. It read as glass once and as its fallback body colour ever after.

Taking a surface back rather than rebuilding it is what keeps the same promise for the panel’s own glass. A surface holds state no element and no stylesheet can hand back — the runtime background a controller set through SetBackground, and the definition it last applied — so a rescan that replaced it dropped the fetched image and fell back to the authored body. That is what the Home screen’s project logo did after every editor UI reload: applied to the surface the reload’s scan had just built, then thrown away by the next scan a re-insertion triggered. A scan therefore re-groups; it does not recreate. It unregisters only the surfaces whose elements the scan no longer finds, and ClearSurfaces — the full release — is left for a root going away for good.

The other order needs more than Find, and this is what SelfManagedClassName is for. A panel root attaches before its descendants — SetPanel gathers the subtree breadth-first and sends AttachToPanelEvent down that list — so a screen toggled back on is scanned a step before the element that would register its own surface gets its own event. In that window the element has no surface, and the scan cannot tell "unclaimed" from "about to be claimed": it adopts the element into the panel’s scope, and the owner’s later Register puts a second surface on top of the first.

So runtime glass built inside a screen root carries glass-self-managed, set once where the element is built and never touched again:

TakeSurface skips a marked element outright, so ownership is settled by what the element is rather than by which callback ran first — no ordering to reason about, and nothing to keep in step as the element is shown, hidden, detached or re-attached. BetterScrollView.ScrollArrow is the worked example; before the marker the arrows joined the panel scope on the first reload and reported a C1 overlap against the screen’s chrome.

An element outside every scanned root does not need the marker — OptionPicker’s list on `panel.visualTree is never queried in the first place — but carrying it there is harmless, and is the safer habit for anything that might later be moved inside a screen.

LiquidGlassPanelTracker is the one caller that wants a surface without the scope its class implies — it groups the panel’s dynamic elements itself, once the whole tree is scanned and draw order is known — and uses the internal RegisterGrouped for that. A scope built at registration would be overwritten by that grouping and orphaned: still ticking, still holding a pyramid, still drawing a snapshot every frame, which is a pyramid per element and the one thing scopes exist to avoid.

For content whose image is only known at runtime (a fetched thumbnail), LiquidGlassContentSurface.SetBackground(texture) overrides both USS texture sources. When the element is authored in UXML rather than built from C#, the panel tracker already owns its surface — reach it with LiquidGlassContentSurface.Find(element) instead of registering a second one, which would leave the two fighting over the element’s material. Passing null drops the override and falls back to the USS body, which is how an element returns to its authored colour while the next image is fetched.

C1 — no two participants in a scope overlap. That is what makes it safe for them to share a snapshot: they never need to sample each other.

C2 — everything a participant should refract is drawn before the first participant of its scope. Non-overlap alone does not give this. A header and a tab bar do not overlap, but if the snapshot were taken at the header and the scrolling content drew between them, the tab bar would refract a screen with no content in it. In practice C2 means authoring the layout the natural way — content first, floating chrome last — and it is what the snapshot’s placement guarantees given that.

Glass placed early in the layout is what breaks it, and it breaks the element furthest down. The agent detail screen is the worked example: making its hero version pill dynamic put a participant at the top of the scroll, so the snapshot moved there and the slide over the bottom of the screen refracted a screen drawn no further than the hero. Two ways out — a glass-scope on the floating chrome, so it snapshots after the scroll, or basic glass on the early element. That screen takes the second: a pill on the hero has one image behind it either way, and a scope of its own is a second panel-texture copy and blur per frame to sample it live.

C1 is checked in the editor (an O(n²) rect overlap test per scope, logged through Log.Write on Category.UI) because it is promised silently in markup and violating it produces a subtly wrong blur rather than anything that announces itself.

The snapshot is a hidden zero-size ImmediateModeElement inserted as the previous sibling of the first participant in draw order. Not a child of the scope container, which would miss content living inside the scope before that participant; and not a first child of the participant either, since generateVisualContent fires after the element’s own background and border, by which point the glass body would already have drawn.

Its callback runs with the panel texture bound and holding exactly everything earlier in z order and nothing later: UIRenderDevice.EvaluateChain flushes every batched draw before entering, and RenderChainCommand.ExecuteNonDrawMesh saves and restores the bound target, the matrices, the scissor and culling around it. (An exception escaping that callback skips every later immediate callback in the frame, so the body is wrapped and a failure disables just its own scope, once, with a log.)

Nothing is deferred or re-ordered. The draw order stays:

B samples a snapshot taken before A, so it does not see A or `A’s children — which under C1 is invisible, and is exactly what C1 is for. The glass bodies keep their natural chain positions, which is what makes z order correct by construction rather than by machinery.

LiquidGlassBackdropPyramid builds the blurred mip chain the participants sample. Mip 0 is the scope’s region copied out of the panel texture with the scene composited under it (which leaves it opaque, so a dynamic glass body needs no alpha), and every deeper level is a half-resolution downsample plus a Kawase blur at its own resolution — so the effective radius doubles per level and a participant reads its own --glass-blur radius off a trilinear lod. Its edge reflection reads a second lod off the same chain, at --glass-reflection-blur, so the mirror ring can be softer or sharper than the body without costing another pyramid.

The pyramid’s resolution is derived from the blur radius rather than being a fixed fraction, so that a requested radius always lands on the same pyramid level. This is what keeps the blur DPI-independent: the panel is ConstantPhysicalSize, so a point-authored radius is a different number of pixels at every DPI, and against a fixed fraction it would slide up and down the levels. A side effect worth knowing: a larger radius makes the pyramid smaller, so big blurs are cheaper than small ones.

Sharing one pyramid between radii that differ splits that rule in two. Every radius read off the chain counts here, a participant’s reflection blur as much as its body blur — they are lods on one texture, so neither end can be sized for only half of them:

Radii far apart in one scope therefore cost what the smallest asks for in resolution and what the largest asks for in levels. A scope whose participants share a radius — the normal case, including a reflection blur left unauthored — costs exactly what one element would.

The region is the union of the participants' bounds, padded by how far their shading actually reads outside them — the wider of the two blur radii’s tap spread, plus the refraction’s lateral throw, both taken from each participant’s own authored values and maximised over the scope, so the padding follows a screen that tunes its glass rather than a fixed number that under-pads at production settings. It is then clamped to the panel and grown to a 64 px size class. Where the edge reflection samples is not padded for: its outward offset reaches further than either term and is left to clamp deliberately, because it mirrors the backdrop rather than showing it, so a clamped tap reads as a slightly duller rim where a clamped body tap would read as a smear.

The region and the mapping into it ride inside each participant’s material definition rather than being read per draw, so the scope has to keep them in step with where its participants actually are. Style and geometry events are not enough and cannot be made enough: they fire on layout, and the things that move floating chrome are transforms — a sidebar sliding in on translate, a button pressing on scale. Both change worldBound with no layout pass at all.

So LiquidGlassPanelTracker.TickScopes re-resolves every scope once per frame, from the manager’s LateUpdate (and EditorTick). The events are kept only because they land in the same frame as the change rather than on the next one. The per-frame path is written to allocate nothing and rewrite nothing when nothing moved — one worldBound read per participant and a state compare — because rebuilding a material definition allocates a property block.

Rotation is not representable as the offset and scale the mapping carries, and is not handled; nothing rotates glass.

Every parameter above is a --glass-* custom property resolved per element by LiquidGlassContentSurface, exactly like the tint — the renderer feature carries no visual settings, only the scene copy’s resolution and its shader reference.

Components.uss authors one set on .glass, which is what makes the look global; it is a convention rather than a mechanism, so a screen that needs a different rim overrides the property and gets :hover states and -unity-material transitions on it for free, like every other glass parameter.

Lengths are in points, and glass works in points all the way to the fragment, so equal values render the same bevel at every DPI. Where a property is not authored at all, the surface’s own Default* constants apply — the single fallback, matching the values above, with nothing else holding a second copy to drift from. None of this depends on the renderer feature, so the look is identical on the quality presets it is absent from.

The copy is worth nothing on a screen with nothing behind the UI, so the feature’s Scene Backdrop switch skips LiquidGlassSceneColorPass outright — no copy, no chain, and the texture released rather than left allocated and stale. Both consumers then fall back on their own, since both read the copy off its global name rather than through a setting: a screen-space body resolves to its --glass-background-color (the manager notices the global going away and rebuilds every surface), and a scope’s mip 0 composites the panel over SceneStandIn, a flat near-black, instead of the scene.

So it costs nothing to look at except where something was showing the scene — which is the case it is meant to be turned off in. Dynamic glass keeps working either way; what it loses is the scene showing through wherever the UI beneath a participant is transparent.

QualityManager drives the switch through LiquidGlassFeature.SceneBackdropEnabled, off whenever the app is outside an interaction and on again on entry, alongside the camera’s post-processing and the interaction-only renderer features — outside one there is no 3D scene up to show. It only ever switches off what the preset authored on: the authored value is captured the first time the feature is seen, which is before any write of its own. Because those writes land on a renderer asset, whose runtime value outlives play mode, it restores every feature it touched on teardown in the editor.

The panel texture is always at native screen resolution, so UI sharpness is independent of the 3D render scale; only the blurred scene content inherits render-scale softness, hidden under the blur. A native-resolution texture also keeps UI Toolkit’s default identity screen-to-panel mapping correct for pointer input.