Represents a raw terminal escape sequence payload to be emitted at a specific region, bypassing the cell-based render pipeline. More...
Public Member Functions | |
| string? | Cleanup (Region region) |
| the next frame (i.e. | |
| IEnumerable< string > | Encode (Region region, ColorProfile profile) |
| Encode the payload as one or more raw terminal escape sequences positioned at region . | |
| IEnumerable< string > | Place (Region region, ColorProfile profile) |
| Re-position content the terminal already holds, without re-transmitting it. | |
| IEnumerable< string >? | Refresh (Region region, ColorProfile profile) |
| Optional per-frame renewal for a payload that has not moved and is already on screen. | |
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. | |
Detailed Description
Represents a raw terminal escape sequence payload to be emitted at a specific region, bypassing the cell-based render pipeline.
Intended for pixel graphics protocols (Kitty, Sixel) where the terminal interprets binary escape blobs rather than styled character cells. Implement this interface and pass an instance to IRenderContext.WriteRawEscape from within a widget's Render method.
Member Function Documentation
◆ Cleanup()
| string? ConsoleForge.Layout.IRawEscapePayload.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.
Implemented in ConsoleForge.Terminal.KittyPayload.
◆ Encode()
| IEnumerable< string > ConsoleForge.Layout.IRawEscapePayload.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.
Implemented in ConsoleForge.Terminal.KittyPayload.
◆ Place()
| IEnumerable< string > ConsoleForge.Layout.IRawEscapePayload.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.
Kitty: a single a=p naming the already-uploaded image id, so a moving image costs one short command per frame rather than its whole payload.
- Parameters
-
region The region the payload occupies this frame. profile Active terminal color profile — may influence encoding.
Implemented in ConsoleForge.Terminal.KittyPayload.
◆ Refresh()
| IEnumerable< string >? ConsoleForge.Layout.IRawEscapePayload.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.
Implemented in ConsoleForge.Terminal.KittyPayload.
Property Documentation
◆ 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.
Implemented in ConsoleForge.Terminal.KittyPayload.
The documentation for this interface was generated from the following file:
- src/ConsoleForge/Layout/IRawEscapePayload.cs
