Mica and acrylic materials

Build and test commands are in CONTRIBUTING. See the reference index for related APIs. Examples in this reference use C++ unless stated otherwise.

Scope

XUI supports two kinds of material:

• A window backdrop asks Windows 11 to draw Mica, Mica Alt, or Desktop Acrylic behind the window.
• An acrylic surface is a Stack that blurs and tints the window pixels painted behind it.

Both are opt-in. Existing windows and stacks keep their solid appearance. Neither material adds a timer or a continuous render loop. High contrast always takes precedence over both materials.

Window backdrops

#include "xui/application.hpp"

xui::WindowOptions options{L"Notes", {720, 480}};
options.visual_style = xui::VisualStyle::winui;
options.backdrop = xui::WindowBackdrop::mica;
xui::Window window(options);
// Later, on the UI thread:
window.set_backdrop(xui::WindowBackdrop::acrylic);
const bool presented = window.backdrop_active();

WindowOptions::backdrop selects the initial request. Window::set_backdrop changes the request before Show or while the window is open. It requires the window's UI thread and rejects a closed window. Window::backdrop returns the request. Window::backdrop_active returns true only while Windows presents the material.

The material appears where XUI does not paint. That includes the window background, the system or custom title bar, and the gaps between controls. Resting caption buttons, unstyled collection backgrounds such as the navigation pane, and unselected title-bar tab rails also show the material. Surfaces, fields, data grids, and other filled controls remain opaque. Place a text-heavy page on a Stack with set_surface(true) to keep its contrast independent of the wallpaper. The control gallery uses this layout: the catalog and margins show the material, and each page is a surface.

While a backdrop is active, XUI:

• extends the DWM frame across the client area and clears unpainted pixels to transparent;
• leaves the caption color to Windows so that the material also covers the system title bar;
• draws text with grayscale antialiasing, because ClearType requires opaque destination pixels;
• repaints native EDIT, RichEdit, and date/time controls through an opaque buffer.

GDI writes zero alpha, so native editors would otherwise blend with the material. The opaque repaint applies after each paint request and after input that can draw outside a paint request. Native text input, selection, IME composition, the caret, and accessibility are unchanged.

Fallback

XUI paints the solid theme background and reports backdrop_active() == false when:

• Windows is older than Windows 11 build 22621;
• Transparency effects is off in Windows settings;
• the window uses high contrast; or
• DWM rejects the material.

XUI reevaluates these conditions after theme, system setting, and DWM composition changes. Rejected materials write a diagnostic to the debugger. Other DWM errors use the window's error path. Windows can also show a solid material, for example in battery saver or for inactive windows. backdrop_active() reports the XUI request, not the pixels that DWM chooses to compose.

Borderless material windows

A backdrop can be combined with WindowOptions::transparent (or Window::set_transparent(true)) before Show. The window is then a non-layered captioned window whose frame is removed in WM_NCCALCSIZE, so it has no visible border, caption, or caption buttons. DWM draws only the solid fallback behind a frameless WS_POPUP; the hidden caption frame is what receives the live material. Unpainted pixels show the material instead of the desktop, and Windows 11 rounds the corners and draws a compositor shadow. The whole window rectangle receives pointer input; there are no pass-through margins. Window::set_drag_region still marks a caption drag area.

xui::WindowOptions options{L"Quick note", {420, 200}};
options.transparent = true;
options.backdrop = xui::WindowBackdrop::acrylic;

The material can change, or be removed, while the window is open. Without a presented material, the window paints its solid theme background. A layered transparent window that was shown without a backdrop cannot add one later; set_backdrop throws std::invalid_argument. The layered software surface is described in borrowed HWND and transparent windows. The floating C# card shows both presentations; --acrylic selects this one.

Restrictions

Mica is the desktop wallpaper, not a blur of other windows. Desktop Acrylic blurs the content behind the window.

Acrylic surfaces

auto flyout = std::make_shared<xui::Stack>(xui::Axis::vertical);
flyout->set_material(xui::SurfaceMaterial::acrylic);
flyout->set_padding({16, 12, 16, 12});
flyout->add(std::make_shared<xui::Label>(L"Recent files"));

Stack::set_material(SurfaceMaterial::acrylic) replaces the solid surface fill. An acrylic stack always reports surface() == true. SurfaceMaterial::solid restores the previous set_surface choice.

Each paint copies the pixels already drawn beneath the stack. XUI then applies a Gaussian blur, a luminosity layer that keeps the hue behind the surface, a tint, and low-opacity noise. The values follow the WinUI AcrylicInAppFillColorDefault resource:

The surface uses the WinUI or Classic surface radius and border. A root style can override the radius, border, and background. An authored background covers the material.

Only pixels painted earlier in the same window can show through. Use Grid cells or earlier siblings to place content behind an acrylic stack. Over a window backdrop, the material tints the transparent pixels and the desktop material shows through. Other application windows and pixels painted after the stack do not affect it.

Disabled transparency effects and high contrast paint the solid fallback color. So does a graphics target that cannot supply Direct2D effects. The blur runs only during a paint. Large acrylic areas increase the cost of every repaint of the window.

Experimental composition presentation

A composition window can show Desktop Acrylic inside any rounded Stack, including on a transparent card. This presentation is experimental and opt-in. Its API and behavior can change.

xui::WindowOptions options{L"Quick note", {440, 240}};
options.transparent = true;
options.composition = true;
xui::Window window(options);

auto card = std::make_shared<xui::Stack>(xui::Axis::vertical);
card->set_material(xui::SurfaceMaterial::backdrop_acrylic);
xui::PartStyleValues shape;
shape.corner_radius = 28.0f;
card->set_control_style_values(xui::StylePart::root, shape);

WindowOptions::composition or Window::set_composition(true) must be chosen before Show. The window then renders through a Direct2D composition swap chain instead of the default HWND target. Each SurfaceMaterial::backdrop_acrylic stack clears its pixels and places a Windows composition backdrop visual beneath them. The visual blurs whatever is behind the window and follows the stack's bounds, rounded corners, and enclosing clips. Its tint follows the light or dark theme.

On a transparent composition window, unpainted pixels show the desktop. The window is a frameless, non-layered window without a DWM border or rounded corners. Its window region follows the painted surfaces and controls, so the empty margins pass pointer input through. Window::set_drag_region still marks a caption drag area.

Native text editors remain native child windows. XUI makes them layered children so that they stay visible above the composition content. Layered child windows require a Windows 8 or later compatibility entry in the application manifest; without it, creating the editor fails with an explicit error.

Restrictions:

• A composition window cannot also request a system backdrop.
• Text uses grayscale antialiasing.
• Without a composition window, or with transparency effects off, backdrop_acrylic paints in-app acrylic or its solid fallback.
• High contrast paints the solid fallback.

Swap chain panels and runtime hosts

A SwapChainPanel in a composition window joins the window's composition tree instead of creating its own DirectComposition target. The producer's pixels compose above the window content, so transparent pixels in a premultiplied producer show what XUI painted beneath the panel, including a backdrop_acrylic stack:

auto card = std::make_shared<xui::Stack>(xui::Axis::vertical);
card->set_material(xui::SurfaceMaterial::backdrop_acrylic);
auto panel = std::make_shared<xui::SwapChainPanel>(L"Scene");
card->add(panel, 1);
// Clear the producer's back buffer to transparent, then draw the scene.

XUI does not paint the panel's field background while a composed producer is attached. Popups, menus, and tooltips over an active panel draw into a separate composition layer above the panel visuals; the producer keeps presenting underneath. A panel inside a popup composes above that layer, so it shows above its popup's face. A popup nested over it, or a tooltip, does not cover it. Both set_swap_chain and set_swap_chain_handle work. The panel keeps its own duplicate of a surface handle. The producer's device is independent of the window's device: after the window recovers its own swap chain, the panel keeps its content.

MediaPlayback and WebContent keep their native child windows, which draw above the composition content. As in other windows, an XUI popup cannot open while their content is active; unload or detach it first.

Overlays and device loss

Popups, flyouts, menu bar submenus, command surfaces, tooltips, and content dialogs work in composition windows. They draw over the window content, including over native editors, and their own native editors are editable. backdrop_acrylic inside a popup paints in-app acrylic: a popup sits above window content, so a desktop backdrop would show through the content beneath it. On a transparent composition card, an open popup receives input over the transparent margin, and a content dialog's dimming layer blocks input to the windows behind the card until it closes. Native context menus and suggestion lists are separate top-level windows and are unaffected. After the graphics device is lost or the display changes, the window recreates its swap chain, rebinds its composition content, and repaints; native editors keep their state.

Windows that do not opt in keep the default presentation. The composition decision report records the measured cost of both paths.

Bindings

The C functions are in xui_layout.h. xui_window_backdrop_set accepts XUI_BACKDROP_NONE, XUI_BACKDROP_MICA, XUI_BACKDROP_MICA_ALT, and XUI_BACKDROP_ACRYLIC. It returns XUI_INVALID_ARGUMENT for another value, to add a backdrop to a layered transparent window that is already shown, or for a composition window. xui_window_backdrop_get writes the request and the active state; either output can be null. xui_stack_material accepts XUI_MATERIAL_SOLID, XUI_MATERIAL_ACRYLIC, and XUI_MATERIAL_BACKDROP_ACRYLIC. xui_window_composition accepts 0 or 1 before Show/Run. It returns XUI_INVALID_ARGUMENT while a system backdrop is requested and XUI_BUSY afterward.

window.SetBackdrop(WindowBackdrop.Mica);
var flyout = window.Stack().Material(SurfaceMaterial.Acrylic);
flyout.Add(window.Label("Acrylic surface"));
bool presented = window.BackdropActive;

Samples and tests

The control gallery's Mica and acrylic page switches the window backdrop and toggles an acrylic surface. Start the gallery with --backdrop mica, --backdrop mica-alt, or --backdrop acrylic to select an initial material. xui_backdrop_window_tests checks the acrylic pixels, fallback, clipping, DWM attributes, and opaque native pixels. The C ABI and C# window tests cover argument validation, threading, and runtime changes. xui_backdrop_window_tests needs an unlocked interactive desktop for its window captures. xui_composition_window_tests checks a transparent composition card over a striped window: blurred stripe edges inside the rounded card, click-through margins and corners, a layered native editor that still edits, and resizing. It also covers popups over native editors, combo box, menu bar, command surface, tooltip, content dialog, suggestion list, and native context menu overlays; popup and dialog hit regions on a transparent card; and recovery from injected target loss, device removal, and display changes. Its panel section checks translucent and surface-handle producers over acrylic, popups and tooltips above an active panel, hiding, detachment, and window target recovery; its runtime host section plays local video and, in builds with WebView2, shows web content. Pass --overlays, --card-overlays, --device-loss, --panels, or --runtime-hosts to run one section. xui_swap_chain_sample --acrylic draws its spinning triangle over desktop acrylic. The floating C# card shows the composition card with --composition.