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 |
Show the zone overlay on all screens.
No arguments.
Hide the zone overlay.
No arguments.
Returns true if the overlay is currently visible.
| Arg | Direction | Type | Description |
|---|---|---|---|
| visible | out | b (bool) | True if overlay is visible. |
Highlight a single zone by UUID.
| Arg | Direction | Type | Description |
|---|---|---|---|
| zoneId | in | s (string) | Zone UUID to highlight. |
Highlight multiple zones at once.
| Arg | Direction | Type | Description |
|---|---|---|---|
| zoneIds | in | as (array<string>) | List of zone UUIDs to highlight. |
Clear all zone highlights.
No arguments.
Get the overlay poll interval in milliseconds.
| Arg | Direction | Type | Description |
|---|---|---|---|
| interval | out | i (int32) | Poll interval in milliseconds. |
Get the minimum zone size in pixels.
| Arg | Direction | Type | Description |
|---|---|---|---|
| size | out | i (int32) | Minimum zone size in pixels. |
Get the minimum zone display size in pixels.
| Arg | Direction | Type | Description |
|---|---|---|---|
| size | out | i (int32) | Minimum zone display size in pixels. |
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. |
Hide the Snap Assist overlay.
No arguments.
Returns true if Snap Assist overlay is visible.
| Arg | Direction | Type | Description |
|---|---|---|---|
| visible | out | b (bool) | True if Snap Assist is visible. |
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. |
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. |
Emitted when overlay show/hide state changes.
| Arg | Direction | Type | Description |
|---|---|---|---|
| visible | out | b (bool) | True if overlay is visible. |
Emitted when the highlighted zone changes.
| Arg | Direction | Type | Description |
|---|---|---|---|
| zoneId | out | s (string) | Currently highlighted zone UUID. |
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). |
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.
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.