Visual Effects

The default build uses Aqueous’s Vulkan renderer integration for rounded corners, damage-aware backdrop blur, HDR color processing, and Auto HDR. Layout geometry remains final and stable; motion is applied at render time instead of repeatedly reconfiguring clients.

Backdrop blur

[blur]
enabled = true
radius = 10
passes = 8
noise = 0.0
contrast = 1.0
brightness = 1.0
vibrancy = 0.0
vibrancy_darkness = 0.0

Higher radius and pass counts increase blur and render cost. noise adds stable screen-space grain; contrast and brightness use 1.0 as neutral; vibrancy controls saturation and its dark-color contribution.

Global blur is the capability switch. Ordered rules select individual windows, layer surfaces, and layer popups:

[[window]]
content_type = "video"
blur = false

[[layer]]
namespace = "waybar"
blur = true
blur_popups = true

The renderer caches and damages blur regions around scene changes rather than blindly redrawing the entire desktop. Set enabled = false to remove global blur work.

Native client blur regions

Vulkan effects builds support ext-background-effect-v1. Compatible DMS and Quickshell clients can request blur directly, including regions with holes or rounded masks, without namespace rules. Global [blur].enabled must be true. An explicit blur = false rule vetoes a request, and a committed client mask takes precedence over rectangular rule fallback. See Layer-shell rules for popup behavior.

dms blur check reports protocol discovery. It can report supported even when runtime blur is disabled; a build without Vulkan effects reports unsupported.

Window opacity

[opacity]
enabled = true
value = 0.94
focus_sensitive = false

Or distinguish focus:

[opacity]
enabled = true
focus_sensitive = true
focused = 1.0
unfocused = 0.90

Opacity values range from 0.0 through 1.0. A rule’s opacity value wins over global/focus-sensitive policy. Full opacity is recommended for latency-sensitive games, direct-overlay candidates, and media that should avoid blending.

Workspace and placement motion

[workspace_transition]
enabled = true
rate = 0.0

rate = 0 uses the compiled default; a larger positive value settles the slide more quickly. Workspace transitions retain the outgoing workspace until the slide completes and use inert surface clones, so clients are not repeatedly configured during motion.

Fullscreen windows participate in workspace slides with an opaque backing behind transparent content. Transitions stay clipped to their owning output, including mixed-scale and rotated setups, while client dimensions and focus remain governed by normal workspace policy. Aqueous still permits only one fullscreen owner per output.

Window placement animation is also compositor-side. Damage-driven frames advance only visual state that is changing. Build with -Danimations=false to remove placement and workspace motion completely.

Rounded corners and decorations

Vulkan-effects builds apply a fixed 12-pixel radius to normal window content and borders. Fullscreen content is square. There is no TOML radius setting; -Dvulkan-effects=false builds a square, no-blur diagnostic compositor.

[layout].force_ssd = true selects server-side mode whenever a native XDG window creates an xdg-decoration object. Aqueous responds to every mode request, including repeated requests that do not change the effective mode, and recalculates the result when configuration reloads or the decoration object is recreated or destroyed.

The legacy org_kde_kwin_server_decoration_manager is also advertised for GTK and older Qt clients. Its display-wide default follows force_ssd and updates on configuration reload.

[layout]
force_ssd = true

This setting controls protocol negotiation; it cannot remove pixels that an application draws inside its own content buffer. A window with decoration capability unavailable did not create an xdg-decoration object, so Aqueous cannot safely strip its custom title bar. Use the application’s own server-decoration or native-title-bar setting when it has one. For toolkit- or version-specific startup switches, use a shell-free [[application]] launch profile.

Inspect the negotiated state with:

aqueousctl windows --json |
  jq '.[] | {app_id, title, decoration}'

For a cooperating client, capability is xdg-decoration and effective becomes server-side. requested records the latest client preference, while configure_pending identifies a request that has not yet received its configure response. client-side with capability: unavailable means an application-side workaround is required rather than a compositor policy change.

Fractional client buffers

[scaling]
buffer_policy = "native"

native advertises the exact output scale. integer-ceil keeps logical geometry unchanged while requesting the next integer backing-buffer scale from fractional-aware roots and popups. It may sharpen specific toolkit text but increases buffer pixel count, memory, and GPU bandwidth. Prefer a selective window rule:

[[window]]
app_id = "com.example.Editor"
layout = "tile"
buffer_scale_policy = "integer-ceil"

HDR and Auto HDR

HDR output selection, peak mastering level, SDR white, and Auto HDR boost are per-output settings. Color-management-v1 advertises supported parametric and Windows HDR descriptions, while rules can override highlight expansion by window or content type. See Outputs and HDR.

Hardware color conversion

The experimental DRM hardware color pipeline can offload supported color conversion while retaining renderer fallback. Configure it in wm.toml:

[render]
color_pipeline = "auto" # auto | off

auto is the default. It skips NVIDIA DRM backends and attempts supported pipelines on other GPUs. off retains the ordinary rendering path. This is startup-only: restart the compositor session after changing it. The optional AQUEOUS_DRM_COLOR_PIPELINE=auto|off startup environment override takes precedence and follows the same NVIDIA exclusion.

This option does not enable HDR itself; use the output HDR setting. Unsupported formats, effects, capture paths, and color operations fall back to renderer processing. Auto HDR expansion remains in the shader. No GPU/display combination has yet completed the project’s physical color acceptance checks; see the color-pipeline source guide.

Screen warming

Eligible SDR Vulkan outputs support experimental warming controlled by a compatible client such as Pearl. HDR outputs and mirrors are ineligible. See Screen warming for setup, status, and restoration.

DRM overlay planes

Direct overlay promotion is disabled by default and startup-only:

[render]
overlay_planes = true

[[window]]
content_type = "video"
overlay_plane = "prefer"
opacity = 1.0
blur = false

Aqueous tests one candidate per output and automatically composes on backend rejection or whenever capture, overlap, effects, clipping, scale, transform, software cursors, or buffer constraints make direct presentation unsuitable. Inspect every decision and counter with:

aqueousctl overlay-planes
aqueousctl overlay-planes --json

Tip

Effects are explicit policy. Disable global work you do not use, then use content-type or identity rules for games and video instead of applying one expensive visual policy to every surface.