Skip to main content

Composite extension

Lets a client (typically a compositing window manager) redirect the rendering of windows into off-screen storage, name that storage as a pixmap, and access a special overlay window stacked above everything else. Usually used together with DAMAGE (ext/damage.md) to learn when the off-screen contents change, and XFIXES (ext/fixes.md) for region arithmetic.

X.require('composite', (err, Composite) => {
    X.require('damage', (err, Damage) => {
        Composite.RedirectWindow(wid, Composite.Redirect.Automatic);
        const pixmap = X.AllocID();
        Composite.NameWindowPixmap(wid, pixmap);
        // pixmap now refers to the off-screen storage of wid;
        // use Damage.Create(damage, wid, ...) to hear about updates
    });
});

The version is negotiated automatically while requiring (the module asks for 0.4); it is available as Composite.major / Composite.minor.

Requests​

QueryVersion(clientMajor, clientMinor, cb)​

Negotiates the protocol version. cb(err, [major, minor]) — the version the server will speak. Called automatically by X.require with 0.4.

RedirectWindow(window, updateType)​

Redirects the hierarchy rooted at window to off-screen storage. updateType is one of Composite.Redirect (Automatic: 0 — the server keeps the screen updated itself, Manual: 1 — the client paints). No reply.

RedirectSubwindows(window, updateType)​

Like RedirectWindow, but redirects all current and future children of window instead of the window itself. Compositing managers typically call this on the root window. No reply.

UnredirectWindow(window)​

Terminates redirection of window started by this client with RedirectWindow. No reply.

UnredirectSubwindows(window)​

Terminates redirection of the children of window started by this client with RedirectSubwindows. No reply.

CreateRegionFromBorderClip(region, window)​

Initializes region (a client-allocated XFIXES region XID) with the border clip of window, i.e. the part of the window not obscured by siblings or ancestors. Operate on it with the XFIXES region requests (ext/fixes.md). No reply.

NameWindowPixmap(window, pixmap)​

Binds pixmap (a client-allocated XID) to the off-screen storage of the redirected window. The pixmap keeps referring to that snapshot of storage even after the window is resized (the server allocates new storage and the name must be re-fetched). Use it like a regular pixmap, e.g. as a CopyArea source. No reply.

GetOverlayWindow(window, cb)​

cb(err, overlayWid) — the XID of the composite overlay window of the screen window is on. The overlay window is mapped above all other windows and is untouched by the server; compositing output is drawn there. The server reference-counts overlay users per client.

ReleaseOverlayWindow(window)​

Drops this client's reference to the overlay window of the screen window is on; the overlay is unmapped when no clients use it. No reply.

Events / errors​

None.

Notes​

  • Composite.Redirect = {Automatic: 0, Manual: 1}.
  • The module negotiates version 0.4; the coordinate-origin translation requests of later protocol revisions are not implemented (a source comment marks the version for bumping once they are).
  • Redirection is reference-counted by the server per window and per client; a second Manual redirect of the same window by another client fails with BadAccess.