mirror of
https://github.com/SpartanJ/eepp.git
synced 2026-09-30 18:20:19 +03:00
45 lines
2.7 KiB
Markdown
45 lines
2.7 KiB
Markdown
# eterm Kitty graphics protocol
|
|
|
|
eterm implements the terminal-receiver side of the Kitty graphics protocol. Protocol parsing,
|
|
decoding, image storage, placement state, animation, and terminal lifecycle integration run on the
|
|
terminal worker. The UI thread consumes immutable placement metadata and an ordered pixel-update
|
|
stream, and exclusively owns the OpenGL texture cache.
|
|
|
|
## Supported features
|
|
|
|
- direct RGB and RGBA transmission, including chunking and zlib compression;
|
|
- POSIX shared-memory transmission, including byte offsets and explicit sizes;
|
|
- PNG transmission;
|
|
- image IDs, image numbers, placement IDs, source cropping, cell geometry, and pixel offsets;
|
|
- root-image rectangle updates, animation frames, frame composition, and animation control;
|
|
- deletion selectors, quiet modes, capability queries, storage quotas, usage hints, and eviction;
|
|
- primary/alternate-screen state, reset, clear, scrolling, margins, scrollback, and resize;
|
|
- Unicode placeholder placements (U+10EEEE and Kitty's combining-diacritic encoding);
|
|
- relative placements, including parent validation, cycle detection, and descendant movement;
|
|
- terminal pixel-size queries and SGR pixel mouse coordinates.
|
|
|
|
Local file and temporary-file transfer media are intentionally not enabled. POSIX shared-memory
|
|
objects are opened read-only and immediately unlinked as required by the protocol. Direct
|
|
transmission remains the portable path and works through SSH.
|
|
|
|
## Resource and threading behavior
|
|
|
|
Decoded root images are stored as premultiplied-independent RGBA8 CPU buffers on the worker. GPU
|
|
textures exist only on the UI/GL thread. Incremental updates carry monotonically increasing sequence
|
|
numbers; a bounded queue gap triggers a complete graphics resynchronization. Image count, placement
|
|
count, APC size, decoded transfer size, and total image storage are bounded. Unreferenced images are
|
|
evicted oldest-first when storage is needed.
|
|
|
|
Graphics follow the same presentation cadence and DEC synchronized-update boundary as text. A
|
|
placement anchored in normal-screen history moves with terminal scrolling and is projected into the
|
|
current scrollback viewport. Margin scrolling clips or removes only placements wholly participating
|
|
in the scrolled region. Resize preserves screen-coordinate placements and reflows Unicode placeholder
|
|
metadata with its text cells.
|
|
|
|
## Compatibility testing
|
|
|
|
The eterm unit suite covers fragmented APC input, malformed/fuzzed commands, raw/zlib/PNG transfer,
|
|
independent image namespaces, replacement, partial updates, placement geometry, scrolling and
|
|
scrollback, screen lifecycle, animation, Unicode placeholders, relative placement graphs, ordered
|
|
worker/UI delivery, queue overflow, and resynchronization.
|