# Mica and acrylic materials

Build and test commands are in [CONTRIBUTING](../contribute-and-explore-designs/contributing.md).
See the [reference index](../index.md) 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

```cpp
#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();
```

| Value | Windows material | Intended use |
| --- | --- | --- |
| `WindowBackdrop::none` | None | The default solid theme background |
| `WindowBackdrop::mica` | `DWMSBT_MAINWINDOW` | Long-lived application windows |
| `WindowBackdrop::mica_alt` | `DWMSBT_TABBEDWINDOW` | Windows with tabbed title bars |
| `WindowBackdrop::acrylic` | `DWMSBT_TRANSIENTWINDOW` | Short-lived or secondary windows |

`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.

```cpp
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](application.md#borrowed-hwnd-and-transparent-windows).
The [floating C# card](https://github.com/zadjii-msft/xui/blob/9e6673cffbb2f4fb320da652937729f1b7a03099/bindings/dotnet/FloatingCard/README.md) 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

```cpp
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:

| Theme | Tint | Tint opacity | Luminosity opacity | Fallback |
| --- | --- | --- | --- | --- |
| Dark | `#2C2C2C` | 0.15 | 0.96 | `#2C2C2C` |
| Light | `#FCFCFC` | 0 | 0.85 | `#F9F9F9` |

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.

```cpp
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:

```cpp
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](https://github.com/zadjii-msft/xui/blob/9e6673cffbb2f4fb320da652937729f1b7a03099/docs/llm/architecture.md#composition-presentation-prototype) records the measured cost of both paths.

## Bindings

| Language | Window backdrop | Acrylic surface | Composition presentation |
| --- | --- | --- | --- |
| C++ | `WindowOptions::backdrop`, `Window::set_backdrop`, `backdrop_active` | `Stack::set_material` | `WindowOptions::composition`, `Window::set_composition` |
| C ABI | `xui_window_backdrop_set`, `xui_window_backdrop_get` | `xui_stack_material` | `xui_window_composition` |
| C# | `Window.SetBackdrop`, `Backdrop`, `BackdropActive` | `Stack.Material` | `Window.SetComposition` |
| Rust | Not available | Not available | Not available |
| `.xui` | Not available | Not available | Not available |

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.

```csharp
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](https://github.com/zadjii-msft/xui/blob/9e6673cffbb2f4fb320da652937729f1b7a03099/bindings/dotnet/FloatingCard/README.md) shows the composition card with `--composition`.