Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
org.phosphor_works.Placement.Overlay

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

Well-known name org.phosphor_works.Placement.Overlay
Source XML org.phosphor_works.Placement.Overlay.xml
Methods 14
Signals 5
Properties 0

Methods

showOverlay()

Show the zone overlay on all screens.

No arguments.

hideOverlay()

Hide the zone overlay.

No arguments.

isOverlayVisible()

Returns true if the overlay is currently visible.

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

highlightZone()

Highlight a single zone by UUID.

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

highlightZones()

Highlight multiple zones at once.

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

clearHighlight()

Clear all zone highlights.

No arguments.

getPollIntervalMs()

Get the overlay poll interval in milliseconds.

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

getMinimumZoneSizePx()

Get the minimum zone size in pixels.

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

getMinimumZoneDisplaySizePx()

Get the minimum zone display size in pixels.

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

showSnapAssist()

Show Snap Assist overlay with candidate windows. Called by KWin effect after dragStopped when snapAssistRequested is true. Only the registered compositor bridge may call it, and any other caller is answered with AccessDenied.

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.

hideSnapAssist()

Hide the Snap Assist overlay.

No arguments.

isSnapAssistVisible()

Returns true if Snap Assist overlay is visible.

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

setSnapAssistThumbnail()

Deliver a window thumbnail to the daemon as raw ARGB32 pixels. Called by the kwin-effect as the fallback for setWindowThumbnailDmabuf, whenever the zero-copy path is turned off or the driver, RHI backend or format cannot carry it. Only the compositor's own process may call it (the process serving the daemon's Wayland connection, or kwin_wayland as the direct child of kwin_wayland_wrapper), and any other caller is answered with AccessDenied. 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.

setWindowThumbnailDmabuf()

Deliver a window thumbnail as a single-plane DMA-BUF (zero-copy GPU path) instead of raw pixels. This is the default transport. The daemon refuses it and returns false when started with PLASMAZONES_DMABUF_THUMBNAILS=0, and on any false the caller must fall back to setSnapAssistThumbnail. Only the compositor's own process may call it, as for the raw-pixel method, and any other caller is answered with AccessDenied. The fd is consumed/duplicated by the daemon's GPU import, so 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 accepted and stored the descriptor. The GPU import is deferred (it runs lazily on the daemon's render thread once the render-completion fence signals), so true means accepted and will display, not already imported. False when the dma-buf path is disabled (PLASMAZONES_DMABUF_THUMBNAILS=0), 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

overlayVisibilityChanged

Emitted when overlay show/hide state changes.

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

zoneHighlightChanged

Emitted when the highlighted zone changes.

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

snapAssistShown

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).

snapAssistThumbnailCacheTrimmed

Emitted when the daemon's idle-grace trim empties its snap-assist thumbnail stores (pixel LRU and dma-buf descriptors). The kwin-effect subscribes and drops its recently-posted dedup set in response, so the next snap-assist re-captures thumbnails the daemon no longer holds. Without this edge the two sides desynchronise permanently after a trim and snap assist falls back to program icons until a daemon restart.

No payload.

snapAssistDismissed

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.