Client-requested background blur

Gnoblin implements ext-background-effect-v1 with the blur capability. A shell can use it to specify which parts of a bar or popup need blur, without blurring transparent margins or shadows. Blur follows the surface alpha.

This page is for client developers. Desktop users can use window effects.

The protocol XML is from Wayland's staging specifications.

Submit a region

1. Create a wl_region in surface-local coordinates.
2. Set it as the effect's blur region.
3. Commit the surface with the matching buffer.

The compositor copies the region. Holes and disjoint rectangles are preserved; the result is clipped to the surface size. Synchronised subsurfaces apply it with their surface transaction.

Clear or destroy

A null or empty region removes blur on the next commit, even when a window rule sets blur for the surface. Destroying the effect returns the surface to its window-rule blur, if any.

Destroying the manager does not destroy existing effects.

After a client sets a blur region through this protocol, Gnoblin uses that region instead of guessing from pixel transparency. Sending an empty region turns blur off; it does not return to automatic detection.

Strength and fades

The protocol supplies shape, not strength. Gnoblin defaults client requests to radius 24; a window rule can override it, including blur = 0.

Foreground icons and text do not punch holes in the material region. The blur fades with the surface's own alpha, so it follows a panel's fade-in and fade-out without help from the client.

Disable the protocol

In init.lua:

gnoblin.configure {
    protocols = {
        ext_background_effect_v1 = false,
    },
}

Log out and back in. This setting controls the global in the Gnoblin session.

Rendering

Layer surfaces in the same stack layer share a backdrop captured before the layer paints. Adjacent panels therefore do not sample each other's tint. Offscreen captures use the same grouping.

Bingux combines material regions per window during scene synchronisation. Its standard regions exclude shadows; clients without protocol support retain their fallback behavior.

Verify a change

Use the devkit to inspect the rendered result with the shell client that owns the layer surface. make builds the standalone session and make test runs native runtime checks; neither tests a shell client's rendered blur. See testing for available checks and their limits. Provide the matching Bingux effects module through QML_IMPORT_PATH.