org.plasmazones.Overlay

Zone overlay visibility, highlighting, shader preview, and Snap Assist.

Well-known name	org.plasmazones.Overlay
Source XML	org.plasmazones.Overlay.xml
Methods	17
Signals	4
Properties	0

Methods

<tt>showOverlay()</tt>

Show the zone overlay on all screens.

No arguments.

<tt>hideOverlay()</tt>

Hide the zone overlay.

No arguments.

<tt>isOverlayVisible()</tt>

Returns true if the overlay is currently visible.

Arg	Direction	Type	Description
visible	out	b *(bool)*	True if overlay is visible.

<tt>highlightZone()</tt>

Highlight a single zone by UUID.

Arg	Direction	Type	Description
zoneId	in	s *(string)*	Zone UUID to highlight.

<tt>highlightZones()</tt>

Highlight multiple zones at once.

Arg	Direction	Type	Description
zoneIds	in	as *(array<string>)*	List of zone UUIDs to highlight.

<tt>clearHighlight()</tt>

Clear all zone highlights.

No arguments.

<tt>getPollIntervalMs()</tt>

Get the overlay poll interval in milliseconds.

Arg	Direction	Type	Description
interval	out	i *(int32)*	Poll interval in milliseconds.

<tt>getMinimumZoneSizePx()</tt>

Get the minimum zone size in pixels.

Arg	Direction	Type	Description
size	out	i *(int32)*	Minimum zone size in pixels.

<tt>getMinimumZoneDisplaySizePx()</tt>

Get the minimum zone display size in pixels.

Arg	Direction	Type	Description
size	out	i *(int32)*	Minimum zone display size in pixels.

<tt>showShaderPreview()</tt>

Show shader preview overlay at given screen coordinates (called from editor Shader Settings dialog).

Arg	Direction	Type	Description
x	in	i *(int32)*	Global X coordinate for preview top-left.
y	in	i *(int32)*	Global Y coordinate for preview top-left.
width	in	i *(int32)*	Preview width in pixels.
height	in	i *(int32)*	Preview height in pixels.
screenId	in	s *(string)*	Screen ID (empty = screen containing x,y).
shaderId	in	s *(string)*	Shader UUID.
shaderParamsJson	in	s *(string)*	JSON map of uniform names to values (from translateParamsToUniforms).
zonesJson	in	s *(string)*	JSON array of zone objects (x,y,width,height in preview pixel coords).

<tt>updateShaderPreview()</tt>

Update existing shader preview geometry and/or params.

Arg	Direction	Type	Description
x	in	i *(int32)*	Preview X position.
y	in	i *(int32)*	Preview Y position.
width	in	i *(int32)*	Preview width.
height	in	i *(int32)*	Preview height.
shaderParamsJson	in	s *(string)*	Updated shader parameters JSON.
zonesJson	in	s *(string)*	Updated zones JSON.

<tt>hideShaderPreview()</tt>

Hide and destroy the shader preview overlay.

No arguments.

<tt>showSnapAssist()</tt>

Show Snap Assist overlay with candidate windows. Called by KWin effect after dragStopped when snapAssistRequested is true.

Arg	Direction	Type	Description
screenId	in	s *(string)*	Screen ID where the snap occurred.
emptyZones	in	a(siiiiiibsssdd) *(array<struct(string,int32,int32,int32,int32,int32,int32,bool,string,string,string,double,double)>)*	Array of EmptyZoneEntry structs: (zoneId, x, y, width, height, borderWidth, borderRadius, useCustomColors, highlightColor, inactiveColor, borderColor, activeOpacity, inactiveOpacity).
candidates	in	a(ssss) *(array<struct(string,string,string,string)>)*	Array of SnapAssistCandidate structs: (windowId, compositorHandle, icon, caption).
success	out	b *(bool)*	True if overlay was shown.

<tt>hideSnapAssist()</tt>

Hide the Snap Assist overlay.

No arguments.

<tt>isSnapAssistVisible()</tt>

Returns true if Snap Assist overlay is visible.

Arg	Direction	Type	Description
visible	out	b *(bool)*	True if Snap Assist is visible.

<tt>setSnapAssistThumbnail()</tt>

Deliver a window thumbnail to the daemon as raw ARGB32 pixels. Called by the kwin-effect; authenticated against /proc/<pid>/exe. Returns true iff the payload was accepted into the daemon's bounded LRU cache. See OverlayAdaptor::setSnapAssistThumbnail in src/dbus/overlayadaptor.cpp for the full validation and trust contract.

Arg	Direction	Type	Description
compositorHandle	in	s *(string)*	KWin internal UUID (EffectWindow::internalId().toString(), braced form).
width	in	i *(int32)*	Image width in pixels. Bounded; oversized values are rejected.
height	in	i *(int32)*	Image height in pixels. Bounded; oversized values are rejected.
pixels	in	ay *(array<byte>)*	Tightly-packed ARGB32 (non-premultiplied) bytes, exactly width*height*4 long.
accepted	out	b *(bool)*	True iff the daemon stored the thumbnail in its LRU cache. False on auth failure, oversize-payload rejection, dimension/byte-count mismatch, or post-shutdown engine teardown. Callers use this to decide whether to mark the handle as recently-posted; a false reply must NOT be treated as success.

<tt>setWindowThumbnailDmabuf()</tt>

Deliver a window thumbnail as a single-plane DMA-BUF (zero-copy GPU path) instead of raw pixels. Experimental: the daemon only accepts it when started with PLASMAZONES_DMABUF_THUMBNAILS set, otherwise returns false and the caller must fall back to setSnapAssistThumbnail. Authenticated against /proc/<pid>/exe like the raw-pixel method. The fd is consumed/duplicated by the daemon's GPU import; the caller may close its copy after the call returns.

Arg	Direction	Type	Description
compositorHandle	in	s *(string)*	KWin internal UUID (EffectWindow::internalId().toString(), braced form).
width	in	i *(int32)*	Image width in pixels. Bounded; oversized values are rejected.
height	in	i *(int32)*	Image height in pixels. Bounded; oversized values are rejected.
drmFormat	in	u *(uint32)*	DRM FourCC pixel format of the buffer (e.g. DRM_FORMAT_ABGR8888).
modifier	in	t *(uint64)*	DRM format modifier (DRM_FORMAT_MOD_* or vendor-specific) describing the buffer's tiling/layout.
stride	in	u *(uint32)*	Plane 0 row stride in bytes.
offset	in	u *(uint32)*	Plane 0 byte offset within the buffer.
fd	in	h *(unix_fd)*	DMA-BUF file descriptor for plane 0. Borrowed for the call; the daemon dup()s it if the import needs the buffer afterward.
fenceFd	in	h *(unix_fd)*	sync_file fence fd that signals when the producer's GPU render into the buffer completes. The daemon waits on it before sampling so a repeated/live producer is not read mid-render. Borrowed for the call.
accepted	out	b *(bool)*	True iff the daemon imported and stored the thumbnail. False when the dma-buf path is disabled (PLASMAZONES_DMABUF_THUMBNAILS unset), the driver/RHI backend can't import it, auth fails, or dimensions are out of range. On false the caller MUST fall back to setSnapAssistThumbnail.

Signals

<tt>overlayVisibilityChanged</tt>

Emitted when overlay show/hide state changes.

Arg	Direction	Type	Description
visible	out	b *(bool)*	True if overlay is visible.

<tt>zoneHighlightChanged</tt>

Emitted when the highlighted zone changes.

Arg	Direction	Type	Description
zoneId	out	s *(string)*	Currently highlighted zone UUID.

<tt>snapAssistShown</tt>

Informational signal: emitted after the daemon has built the Snap Assist overlay. The kwin-effect drives thumbnail capture independently as part of the showSnapAssist call sequence (not in response to this signal); the signal is exposed for external observers (KCMs, debugging tools).

Arg	Direction	Type	Description
screenId	out	s *(string)*	Screen ID where snap occurred.
emptyZones	out	a(siiiiiibsssdd) *(array<struct(string,int32,int32,int32,int32,int32,int32,bool,string,string,string,double,double)>)*	Array of EmptyZoneEntry structs: (zoneId, x, y, width, height, borderWidth, borderRadius, useCustomColors, highlightColor, inactiveColor, borderColor, activeOpacity, inactiveOpacity).
candidates	out	a(ssss) *(array<struct(string,string,string,string)>)*	Array of SnapAssistCandidate structs: (windowId, compositorHandle, icon, caption).

<tt>snapAssistDismissed</tt>

Informational signal: emitted when the Snap Assist overlay closes — whether through a user pick, an Escape / backdrop dismiss, an external hideSnapAssist() D-Bus call, or a screen-change cancel. Pairs with snapAssistShown so external observers (KCMs, kwin-effect, debugging tools) can mirror the visible/hidden state without polling isSnapAssistVisible. Carries no payload; the dismiss reason is intentionally not surfaced because the daemon collapses every dismiss path through the same internal IOverlayService::snapAssistDismissed signal.

No payload.