Desktop backdrops

Expose the desktop through selected elements and request native blur behind them. Apply the API to a sidebar, header, card or in-window floating panel. Multiple regions can use different tints.

Enable the feature

desktop-backdrop is disabled by default in argui-runtime and argui-platform. Enable the feature in both crates; it is independent of native popovers and WGSL effects.

argui-platform = { version = "0.4.0", features = ["desktop-backdrop"] }
argui-runtime = { version = "0.4.0", features = ["desktop-backdrop"] }

Configure the window at creation, then choose regions while rendering:

use argui_core::{BackdropMaterial, Color};
use argui_platform::WindowConfig;
use argui_ui::{DesktopBackdrop, Element, length};

let window = WindowConfig {
    desktop_backdrop: Some(BackdropMaterial::Sidebar),
    ..WindowConfig::default()
};
let glass = DesktopBackdrop::new(
    Color::srgba(0.08, 0.09, 0.12, 0.72), // Active tint and opacity.
    Color::srgb(0.08, 0.09, 0.12),       // Fallback without native support.
).inactive_tint(Color::srgba(0.08, 0.09, 0.12, 0.90));

let sidebar = Element::column([Element::text("Navigation")])
    .width(length(260.0))
    .desktop_backdrop(glass);
let content = Element::column([Element::text("Content")])
    .grow(1.0)
    .background(Color::WHITE);
let root = Element::row([sidebar, content]);

Ancestors must remain transparent: an opaque background hides the desktop. Text and controls retain their own opacity. fallback is used on unsupported surfaces, on the web and when high contrast disables blur. It may be translucent if the application explicitly accepts transparency without blur.

Add or remove .desktop_backdrop(...) and notify the model to toggle the effect. Removing the last region disables native blur. glass.blur(false) uses only fallback and inactive_fallback; .blur(true) requests blur again. The window's Glass, Sidebar and Header material hints may render identically on some systems. Different windows can choose different materials.

WindowEnvironment::desktop_backdrop_available reports whether the backend and GPU surface support the request. The compositor can still reduce the effect according to its preferences and window state. Native errors emit RuntimeEvent::DesktopBackdropUnavailable and use fallback without stopping the application.

Controls and limits

• Active and inactive RGBA tints are per element. .inactive_fallback(color) sets the unsupported inactive background; it defaults to fallback.
• Regions follow layout, scrolling, transforms and rounded clips. Native masks round inward to logical pixels.
• Alpha controls background visibility, not blur radius. The operating system chooses the blur kernel.
• argui-effects filters affect Argui content and cannot read other applications.
• Detached native popovers currently use opaque rendering and fallback. In-window popovers and independently configured application windows support this API.

Platform adapters

argui_platform::desktop_backdrop::NativeBackdrop receives visible regions and preferences from the runtime. Shared geometry stays independent of OS APIs; native handles remain retained until their effects are destroyed.

On Windows, renderer fallback is enabled by default. Startup first tries DirectX 12 with DirectComposition, then DirectX 12 with an opaque HWND surface, and finally Vulkan. The runtime emits RuntimeEvent::RendererFallback when a compatibility renderer is selected and disables the desktop backdrop for that session. Applications can require only the preferred DirectX 12 DirectComposition path when diagnosing GPU or driver failures:

let renderer = argui_render::RendererConfig::default().renderer_fallback(false);

If every enabled configuration fails, RuntimeEvent::RendererFailed contains each attempt and its initialization error.

Compositor support is detected at runtime. When neither supported Wayland blur protocol is advertised, Argui paints the configured fallback color.

References: Wayland protocol, KDE WindowEffects, DWM backdrop types, NSVisualEffectView.

Validation

Paint and layout tests cover invalidation, clipping, transforms, fallback and content opacity. The opt-in native_desktop_backdrop test verifies X11 requests and capability removal on a private server; it does not simulate visible blur. Check actual backdrop appearance on each compositor and operating system. Follow Linux graphical testing for GUI checks. Windows and macOS adapters have been cross-compiled; their appearance still needs validation on those systems.