On-screen display — a double-buffered placement of a canvas in the terminal.
Each :update() re-transmits the canvas pixels under a FIXED image id and
re-places them under a FIXED placement id, which atomically replaces the
previous frame. Pixels travel via a fresh-per-frame POSIX shared-memory object
(the terminal unlinks it after reading — so it never leaks), falling back to
inline base64 if shm fails.
Anchoring:
"absolute" — placed at terminal cell (row, col), cursor restored after.
"cursor" — placed relative to the current cursor: jump up up lines
(default rows+1) and to column col, then restore — so the
image rides along behind/with the most recent output (as the
matrix rain does behind text at a negative z-index).
Image/placement ids come from alloc_id / alloc_placement so independent
graphics apps never collide on a hardcoded id.
| Name | Signature |
|---|---|
alloc_id | alloc_id() -> id |
alloc_placement | alloc_placement() -> pid |
display | display(canvas, opts) -> display |
alloc_id() ->
id
Allocate a unique Kitty image id
alloc_placement() ->
pid
Allocate a unique Kitty placement id
display(
canvas,opts) ->display
Create an on-screen display for a canvas
opts shape:
| Name | Deafult | Description |
|---|---|---|
anchor | absolute | cursor or omit for current cursor |
row/col | cell position for absolute, column for cursor anchor | |
up | rows+1 | lines to jump up for cursor anchor |
z | 0 | z-index; use negative to composite behind text |
cols/rows | scale the image into this cell box via the Kitty c/r keys; omit for natural pixel size) | |
no_cursor_move | true | |
transport | shm | direct for inline base64 |
id/placement | default freshly allocated |
Methods:
:show()
:update() -- both transmit+place a frame
:hide() -- drop the placement, keep the image data
:destroy() -- delete image + data
:set_anchor(row, col)