IRawEscapePayload implementation for the Kitty terminal graphics protocol. More...
Public Member Functions | |||||
| string? | Cleanup (Region region) | ||||
the next frame (i.e.the widget was removed or moved). Return null when no cleanup is required. Kitty implementations use this to delete the placed image by its image-id, preventing ghost images after a widget is unmounted.
| |||||
| IEnumerable< string > | Encode (Region region, ColorProfile profile) | ||||
Encode the payload as one or more raw terminal escape sequences positioned at region .Multiple strings are supported for protocols that require chunked transmission (e.g. Kitty's 4096-byte base64 chunks). The framework emits a cursor-move sequence to region 's top-left corner immediately before the first string.
| |||||
| IEnumerable< string > | Place (Region region, ColorProfile profile) | ||||
| Re-position content the terminal already holds, without re-transmitting it.Called when this payload was present last frame at a different region — the scrolling case. The framework has already emitted Cleanup for the old region, so this is not optional: returning nothing leaves the payload off the screen entirely. The default re-runs Encode, which is correct for any protocol without a cheaper way to move content; override it when one exists. | |||||
| IEnumerable< string >? | Refresh (Region region, ColorProfile profile) | ||||
| Optional per-frame renewal for a payload that has not moved and is already on screen.Returning null — the default — means a stationary payload costs nothing, which is the common case. Implement this only when the terminal loses a placement that is left alone, e.g. tmux re-render cycles moving the outer terminal's cursor between frames. Motion is Place's job, not this one; a protocol that renews unconditionally repaints every visible payload at the frame rate, which reads as flicker. | |||||
Properties | |
| int | ContentHash [get] |
| Stable identity for this payload's visual content — equal hashes mean the terminal already holds this content and does not need it transmitted again.The framework tracks payloads across frames by this value, not by region. A payload whose hash was present last frame is re-placed via Place instead of re-encoded, wherever it has moved to; one whose hash is new is sent through Encode. This is what lets a payload move every frame — a scrolling row of images — without re-uploading it. Change the hash whenever the content changes, so the next frame re-encodes. | |
Detailed Description
IRawEscapePayload implementation for the Kitty terminal graphics protocol.
Member Function Documentation
◆ Cleanup()
| string? ConsoleForge.Terminal.KittyPayload.Cleanup | ( | Region | region | ) |
the next frame (i.e.the widget was removed or moved). Return null when no cleanup is required. Kitty implementations use this to delete the placed image by its image-id, preventing ghost images after a widget is unmounted.
- Parameters
-
region The region this payload last occupied.
Deletes the one placement at region , not every placement of the image: the same artwork can legitimately be on screen twice — a show appearing in two shelves — and removing one must not blank the other. The image data itself stays in the terminal, so putting it back costs a placement rather than an upload.
Implements ConsoleForge.Layout.IRawEscapePayload.
◆ Encode()
| IEnumerable< string > ConsoleForge.Terminal.KittyPayload.Encode | ( | Region | region, |
| ColorProfile | profile ) |
Encode the payload as one or more raw terminal escape sequences positioned at region .Multiple strings are supported for protocols that require chunked transmission (e.g. Kitty's 4096-byte base64 chunks). The framework emits a cursor-move sequence to region 's top-left corner immediately before the first string.
- Parameters
-
region The terminal region allocated for this payload. profile Active terminal color profile — may influence encoding.
When inside tmux the first chunk includes an embedded cursor-move so that the outer terminal (WezTerm, etc.) receives cursor-position + image as one atomic DCS passthrough. This is necessary because tmux handles CSI cursor-moves internally and flushes them to the outer terminal independently of APC passthroughs, causing a position race if they are sent separately. Outside tmux sequences are emitted raw; the cursor-move is emitted by ConsoleForge.Layout.RenderContext immediately before calling Encode, so no extra positioning is needed here.
Implements ConsoleForge.Layout.IRawEscapePayload.
◆ Place()
| IEnumerable< string > ConsoleForge.Terminal.KittyPayload.Place | ( | Region | region, |
| ColorProfile | profile ) |
Re-position content the terminal already holds, without re-transmitting it.Called when this payload was present last frame at a different region — the scrolling case. The framework has already emitted Cleanup for the old region, so this is not optional: returning nothing leaves the payload off the screen entirely. The default re-runs Encode, which is correct for any protocol without a cheaper way to move content; override it when one exists.
Moving an image costs one a=p, not a re-upload: Kitty separates transmit (a=t) from place (a=p) precisely so already-held image data can be repositioned. The framework has already deleted the placement at the old region, and the placement id here is derived from the new one.
Implements ConsoleForge.Layout.IRawEscapePayload.
◆ Refresh()
| IEnumerable< string >? ConsoleForge.Terminal.KittyPayload.Refresh | ( | Region | region, |
| ColorProfile | profile ) |
Optional per-frame renewal for a payload that has not moved and is already on screen.Returning null — the default — means a stationary payload costs nothing, which is the common case. Implement this only when the terminal loses a placement that is left alone, e.g. tmux re-render cycles moving the outer terminal's cursor between frames. Motion is Place's job, not this one; a protocol that renews unconditionally repaints every visible payload at the frame rate, which reads as flicker.
Renews a stationary placement with a cheap a=p. This exists for tmux: its re-render cycles move the outer terminal's cursor between frames, so a placement that is not renewed drifts out of position.
Outside tmux it returns null, deliberately. Nothing moves an image that stayed put, and a=p creates an additional placement rather than updating the existing one — so renewing every frame made the terminal redraw every visible image at the frame rate, which reads as flicker on a screen full of artwork. An image that actually moved goes through Place instead, in or out of tmux.
Implements ConsoleForge.Layout.IRawEscapePayload.
The documentation for this class was generated from the following file:
- src/ConsoleForge/Terminal/KittyProtocol.cs
