Skip to content

WIP feature: add driftwm decal drawing - #344

Draft
Granitosaurus wants to merge 4 commits into
malbiruk:mainfrom
Granitosaurus:decals-upstream
Draft

Granitosaurus wants to merge 4 commits into
malbiruk:mainfrom
Granitosaurus:decals-upstream

Conversation

@Granitosaurus

@Granitosaurus Granitosaurus commented Nov 14, 2026 •

Copy link
Copy Markdown

Add decal drawing API for drawing images directly on canvas. Using dirft msg decal commands images can be added, moved, scaled, fliped and discovered which creates opportunity for cool applications like https://github.com/Granitosaurus/driftwm-stickers:

image

Progress:

  • add initial implementation
  • evaluate UX and design
  • full review

What it does

A decal is a still image the compositor draws at a fixed canvas position: a landmark for a cluster of windows, or an anchor you can spot from a zoomed-out view. No window, no client process.

driftwm msg decal add ~/stickers/rocket.png --fit 256
driftwm msg decal move 3 400 -250
driftwm msg decal scale 3 0.5
driftwm msg decal flip 3
driftwm msg decal list / remove 3
driftwm msg pointer                      # pointer position in canvas coordinates
[mouse.on-canvas]
"mod+right"       = "move-decal"      # drag the decal under the pointer
"mod+shift+wheel-scroll" = "scale-decal"  # grow / shrink it, aspect ratio and center kept

Commits

The branch is four commits that each build with cargo check --all-targets, so it can be read or split in pieces:

  1. Add decals: Decal model, decals.json persistence, rendering below windows, decal add | list | remove.
  2. Drag: move-decal mouse action, decal move, msg pointer.
  3. Scale: scale-decal scroll action, decal scale.
  4. Flip: decal flip.

If you would rather review (1) alone and take the rest as follow-ups, they apply in order.

Design notes

  • Rendering. A TextureRenderElement per decal, pixel-snapped like other canvas elements, drawn between the background and the windows. Pixels are premultiplied at upload; textures are cached per path (and per flip state) and dropped when the last decal using them is removed.
  • Flip uploads mirrored pixels instead of using Transform::Flipped: smithay converts the source rect of a flipped element against the destination size, so any scale other than 1 samples the wrong region. There is a pixel test at scale 0.5 for this. The cost is a second texture for an image that is shown both ways.
  • Input. move-decal / scale-decal only act where no client is under the pointer (decals are below windows), and otherwise fall through to the binding's normal behaviour. A drag is a PointerGrab that keeps the offset from the pointer. Scrolling is a continuous MouseAction because wheel-up / wheel-down only run keyboard actions.
  • Persistence. decals.json in the state dir, written on change (debounced for drags and scroll, 300 ms) and flushed on quit and on signals. Additive fields (flip) use serde(default) so older files load.
  • Limits so a script cannot wedge the compositor: 256 decals, 32 MiB / 8192 px per image, scale 0.01 to 64, position within ±1e7. Out-of-range input is refused with a message.
  • IPC. New Request::Decal(..) and Request::Pointer; nothing changes for existing requests. decal writes are classed as mutating.
  • No config option is needed to use the feature; the two mouse actions are unbound by default.

Known limitations

  • The hit area is the full image rectangle; transparent corners still count for drag, scale and decal remove / flip with no id.
  • A decal under a window can't be grabbed with the mouse. The decal commands still reach it by id.
  • Still images only (anything the image crate decodes); no animation.
  • A flipped image uses a second texture when it is also shown upright by another decal.

Verification

  • cargo fmt --check, cargo clippy --all-targets -- -D warnings, cargo test -- --include-ignored --skip soak and the soak test: all green locally via dev/scripts/ci-local.
  • New tests: model and persistence (incl. old files without flip, bad files); IPC dispatch for add / list / remove / move / scale / flip / pointer, incl. refusals; mouse drag and scroll through the real input path; rendering pixel tests (below windows, transparency, flip mirrors in place, at scale 1 and 0.5); docs/cli.md examples parse.
  • By hand on real hardware (NixOS laptop, real session, mouse): decal add through a picker, move-decal dragging and scale-decal with the wheel all behave as described. Not yet exercised by hand: decal flip after the final rendering fix (it is covered by the pixel tests at scales 1 and 0.5), and a trackpad.

Docs

docs/decals.md (new), docs/ipc.md, the generated docs/cli.md and docs/config.md (from config.reference.toml).

Granitosaurus and others added 4 commits November 14, 2026 09:48
`driftwm msg decal add|list|remove` places a still image at a canvas point,
drawn by the compositor below every window and widget. A decal is not a
window, so no drag, snap, fit, tiling or Alt-Tab machinery ever sees it, and
it needs no client process or relaunch to survive a restart.

- decals.rs: serde types, bounds, atomic read/write of decals.json beside
  session.json (always saved, independent of the [session] restore flags).
- state/decals.rs: registry, hit-test for `remove` under the pointer; the
  image size is read from the file header when placed, so bad or oversized
  files are refused at the command.
- render/decals.rs: one cached TextureBuffer per image (stable element id for
  damage tracking), premultiplied on upload, explicit texel src so a scaled
  decal samples the whole texture.
- IPC verb, CLI subcommand, docs/decals.md, regenerated docs/cli.md.

Tests: 15 headless fixture tests (placement, cursor placement, hit-test,
bounds, persistence) and 3 GL pixel tests (placement, premultiplied blend,
scaling, drawn below a window).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A flipped decal uploads horizontally mirrored pixels as its own texture,
cached per (path, flip). Flipping with a GPU transform is not an option:
smithay converts the source rect of a Transform::Flipped element against
the destination size, so any scale other than 1 samples the wrong region.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@Granitosaurus Granitosaurus changed the title feature: add driftwm decal drawing WIP feature: add driftwm decal drawing Nov 16, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant