Koya/Screenshot - Koya Documentation

Koya/Screenshot captures frames from a Wayland output using the wlr-screencopy protocol and stores them in the renderer's texture pool.

Textures are stored at /ram/screenshot/<id> and can be assigned to any UI element immediately. Reusing the same <id> overwrites the texture in VRAM safely.

Import #

Functions #

capture

Captures the specified display (or the window's display when omitted) and writes a VRAM texture into the pool at /ram/screenshot/<id>.

source: "wayland" uses compositor screencopy (default).
source: "vulkan" captures the engine-rendered swapchain image for the target window.
Returns true on success.

capture(windowId, { id: string, source?: "wayland"|"vulkan", display?: string, cursor?: boolean, mipmaps?: boolean }): Promise<boolean>

Example #

Capture the current Wayland output (without the cursor) and display it as a texture on an overlay. This is the pattern used for lock-screen backgrounds or any feature that needs a frozen snapshot of the desktop.

import * as Compositor from 'Koya/Compositor';
import * as UI from 'Helix/UserInterface';
import * as Screenshot from 'Koya/Screenshot';

const win = await Compositor.createWindow({
  role: 'overlay', anchor: 'top-left', size: { x: 640, y: 360 }
});
const id = await UI.createElement(win, {
  renderable: { type: 'box', aabb: { min: { x: 0, y: 0 }, max: { x: 640, y: 360 } }, position: { x: 0, y: 0 } }
});

if (await Screenshot.capture(win, { id: 'lock', source: 'wayland', cursor: false })) {
  await UI.setTexture(win, id, '/ram/screenshot/lock');
}

Notes #

On compositors providing y-inverted frames or different shm formats, Koya converts to RGBA internally.
If the compositor doesn't advertise wlr-screencopy, the call will fail (returns false).
Vulkan source can return false on the first call while capture is scheduled; call again next tick.

<- Koya/Compositor Koya/Image ->