API Reference on KGP

Command

Mon, 01 Jan 0001 00:00:00 +0000

Command represents a complete Kitty Graphics Protocol command.

Creating Commands

Commands are created via builders. Do not instantiate Command directly.

 go
 
 
cmd := kgp.NewTransmitDisplay().
 Format(kgp.FormatPNG).
 TransmitDirect(data).
 Build() // Returns *Command

Methods

Encode

 go
 
func (c *Command) Encode() string

Returns the complete escape sequence as a string, including the APC delimiters ESC_G and ESC\. Payload data is base64-encoded.

EncodeChunked

 go
 
func (c *Command) EncodeChunked(maxChunkSize int) []string

Splits the payload into multiple escape sequences for chunked transmission. Required when payload exceeds terminal limits (e.g., over SSH).

TransmitBuilder

Mon, 01 Jan 0001 00:00:00 +0000

Builds transmit or transmit+display commands. Transmit uploads image data; transmit+display also creates the initial placement.

Constructors

NewTransmit

 go
 
func NewTransmit() *TransmitBuilder

Creates a transmit-only builder (action t). Image data is uploaded but not displayed. Use with NewPut() for placements.

NewTransmitDisplay

 go
 
func NewTransmitDisplay() *TransmitBuilder

Creates a transmit-and-display builder (action T). Uploads and displays in one command.

Methods

Image Identification

Method	Signature	Description
`ImageID`	`(id uint32)`	Set image ID (auto-generated if omitted)
`ImageNumber`	`(num uint32)`	Set image number (application-specific, non-unique)

Format & Dimensions

Method	Signature	Description
`Format`	`(format Format)`	Set format: `FormatRGB`, `FormatRGBA`, `FormatPNG`
`Dimensions`	`(width, height int)`	Required for RGB/RGBA formats

Transmission

Method	Signature	Description
`TransmitDirect`	`(data []byte)`	Embed data in escape sequence (default)
`TransmitFile`	`(path string)`	Read from file path
`TransmitFileWithOffset`	`(path string, offset, size int)`	Read from file with byte range
`ValidateTempPath`	`(path string) error`	Validate temporary-file path requirement
`TryTransmitTemp`	`(path string) (*TransmitBuilder, error)`	Temporary file with error return on invalid path
`TransmitTemp`	`(path string)`	Temporary file; panics if path is invalid
`TransmitSharedMemory`	`(name string, size int)`	POSIX shared memory object
`Compress`	`()`	Enable ZLIB compression (use with pre-compressed data)

Placement Options

Method	Signature	Description
`PlacementID`	`(id uint32)`	Set placement ID for initial placement
`CellOffset`	`(x, y int)`	Pixel offset within starting cell
`DisplaySize`	`(columns, rows int)`	Display size in terminal cells
`SourceRect`	`(x, y, width, height int)`	Crop source to rectangle
`ZIndex`	`(z int)`	Z-index (negative=below text, positive=above)
`CursorMovement`	`(move bool)`	`true`=cursor moves after, `false`=stays
`RelativeTo`	`(parentImageID, parentPlacementID uint32, offsetH, offsetV int)`	Relative positioning
`VirtualPlacement`	`()`	Invisible placement for Unicode placeholders

Response

Method	Signature	Description
`ResponseSuppression`	`(mode ResponseSuppression)`	`ResponseAll`, `ResponseErrorsOnly`, `ResponseOKOnly`

Build

 go
 
func (tb *TransmitBuilder) Build() *Command

Constructs the final *Command. Call exactly once per builder.

PutBuilder

Mon, 01 Jan 0001 00:00:00 +0000

Creates placement commands for existing images. Use after NewTransmit() to display an image in multiple locations or with different display parameters.

Constructor

NewPut

 go
 
func NewPut(imageID uint32) *PutBuilder

Creates a put builder for the specified image. The image must already exist (transmitted previously).

Methods

Image & Placement Identification

Method	Signature	Description
`ImageNumber`	`(num uint32)`	Application-specific image number (non-unique)
`PlacementID`	`(id uint32)`	Set placement ID (auto-generated if omitted)

Display Options

Method	Signature	Description
`CellOffset`	`(x, y int)`	Pixel offset within starting cell
`DisplaySize`	`(columns, rows int)`	Display size in terminal cells
`SourceRect`	`(x, y, width, height int)`	Display only a region of the source image
`ZIndex`	`(z int)`	Z-index (negative=below text, positive=above)
`CursorMovement`	`(move bool)`	`true`=cursor advances, `false`=cursor stays
`RelativeTo`	`(parentImageID, parentPlacementID uint32, offsetH, offsetV int)`	Position relative to parent placement
`VirtualPlacement`	`()`	Invisible placement for Unicode placeholders

Response

Method	Signature	Description
`ResponseSuppression`	`(mode ResponseSuppression)`	Control which responses are sent

Build

 go
 
func (pb *PutBuilder) Build() *Command

DeleteBuilder

Mon, 01 Jan 0001 00:00:00 +0000

Builds delete commands. Delete modes determine what is removed and whether image data is freed.

Constructor

NewDelete

 go
 
func NewDelete(mode DeleteMode) *DeleteBuilder

Creates a delete builder. The mode must be one of the DeleteBy* constants.

Methods

Mode-specific parameters (call only the ones relevant to the chosen mode):

Method	Signature	Used With Modes
`ImageID`	`(id uint32)`	`DeleteByImageID`, `DeleteByImageIDFree`
`ImageNumber`	`(num uint32)`	`DeleteByImageNumber`, `DeleteByImageNumberFree`
`PlacementID`	`(id uint32)`	`DeleteByPlacementID`, `DeleteByPlacementIDFree`
`Cell`	`(x, y int)`	`DeleteByCell`, `DeleteByCellFree`
`Column`	`(x int)`	`DeleteByColumn`, `DeleteByColumnFree`
`Row`	`(y int)`	`DeleteByRow`, `DeleteByRowFree`
`ZIndex`	`(z int)`	`DeleteByZIndex`, `DeleteByZIndexFree`
`IDRange`	`(startID, endID int)`	`DeleteByIDRange`, `DeleteByIDRangeFree`

Method	Signature	Description
`ResponseSuppression`	`(mode ResponseSuppression)`	Control responses

Note: For DeleteByImageID, DeleteByImageIDFree, DeleteByPlacementID, and DeleteByPlacementIDFree, you must also set ImageID via ImageID() when the mode requires it. The protocol uses i for both image ID and (in some modes) other purposes; the builder maps these correctly.

Animation Builders

Mon, 01 Jan 0001 00:00:00 +0000

Animation support uses three builders: FrameBuilder (add frames), AnimateBuilder (control playback), and ComposeBuilder (compose frames).

FrameBuilder

Adds animation frames to an existing image.

NewFrame

 go
 
func NewFrame(imageID uint32) *FrameBuilder

Methods

Method	Signature	Description
`FrameData`	`(data []byte)`	Raw frame image data
`Format`	`(format Format)`	Format for frame (required for RGB/RGBA)
`Dimensions`	`(width, height int)`	Required for RGB/RGBA
`FrameNumber`	`(frameNum uint32)`	Edit existing frame (replace instead of append)
`BackgroundFrame`	`(frameNum uint32)`	Frame to use as background (0 = base image)
`Gap`	`(milliseconds uint32)`	Delay before next frame in ms
`Composition`	`(mode CompositionMode)`	`CompositionBlend` or `CompositionReplace`
`BackgroundColor`	`(rgba uint32)`	32-bit RGBA background color
`ResponseSuppression`	`(mode ResponseSuppression)`	Control responses

AnimateBuilder

Controls animation playback.

QueryBuilder

Mon, 01 Jan 0001 00:00:00 +0000

Queries terminal capabilities. Send a minimal graphics command; the terminal responds with OK if supported.

Constructor

NewQuery

 go
 
func NewQuery() *QueryBuilder

Methods

Method	Signature	Description
`Format`	`(format Format)`	Format to test
`Dimensions`	`(width, height int)`	Test dimensions
`TransmitMedium`	`(medium TransmitMedium)`	Medium to test
`TestData`	`(data []byte)`	Minimal payload (e.g., 3 bytes for RGB)

Build

 go
 
func (qb *QueryBuilder) Build() *Command

QuerySupport

Convenience function for the most common query:

Response

Mon, 01 Jan 0001 00:00:00 +0000

Parsed terminal response to a graphics command.

Struct

 go
 
 
type Response struct {
 ImageID uint32 // Assigned image ID
 ImageNumber uint32 // Assigned image number (if requested)
 PlacementID uint32 // Assigned placement ID
 Success bool // true if OK
 ErrorCode string // e.g., "ENOSPC", "ENOENT", "EINVAL"
 Message string // Error message (if any)
}

ParseResponse

 go
 
func ParseResponse(response string) (*Response, error)

Parses a terminal response string in permissive mode. This parser accepts responses with or without APC markers and tolerates unknown/malformed control-data pairs when possible.

Constants

Mon, 01 Jan 0001 00:00:00 +0000

Formats

Constant	Value	Description
`FormatRGB`	24	24-bit RGB (3 bytes per pixel)
`FormatRGBA`	32	32-bit RGBA (4 bytes per pixel, default)
`FormatPNG`	100	PNG with embedded dimensions

Transmit Mediums

Constant	Value	Description
`TransmitDirect`	`"d"`	Embed data in escape sequence (default)
`TransmitFile`	`"f"`	Read from regular file
`TransmitTemp`	`"t"`	Temporary file (terminal deletes after read)
`TransmitSharedMem`	`"s"`	POSIX shared memory

Compression

Constant	Value
`CompressionZlib`	`"z"`

Delete Modes

Preserve data (lowercase): Delete placement(s) but keep image data in memory.

Helper Functions

Mon, 01 Jan 0001 00:00:00 +0000

Convenience functions for common operations.

Transmit Helpers

TransmitImage

 go
 
func TransmitImage(img image.Image) (*Command, error)

Transmits and displays an image.Image as PNG. Uses image/png for encoding.

TransmitImageWithID

 go
 
func TransmitImageWithID(img image.Image, imageID uint32) (*Command, error)

Same as TransmitImage but with a specific image ID.

TransmitImageRGBA

 go
 
func TransmitImageRGBA(img image.Image, compress bool) (*Command, error)

Transmits as raw RGBA. If compress is true, applies ZLIB compression.

Delete Helpers

Function	Description
`DeleteAll()`	Delete all placements, preserve data
`DeleteAllFree()`	Delete all and free memory
`DeleteImage(imageID uint32)`	Delete placements of image, preserve data
`DeleteImageFree(imageID uint32)`	Delete image and free memory
`DeleteAtCursor()`	Delete at cursor, preserve data
`DeleteAtCursorFree()`	Delete at cursor and free

Animation Helpers

Function	Description
`PlayAnimation(imageID uint32)`	Play using protocol `LoopCount(2)`
`PlayAnimationLoop(imageID uint32)`	Play with infinite looping
`PlayAnimationWithLoopCount(imageID, count uint32)`	Play with explicit protocol loop-count value
`StopAnimation(imageID uint32)`	Stop at current frame
`ResetAnimation(imageID uint32)`	Stop and reset to first frame

Image Utilities

Conversion

Function	Description
`ImageToRGBA(img image.Image) []byte`	Convert to raw RGBA bytes
`ImageToRGB(img image.Image) []byte`	Convert to raw RGB bytes
`ImageToPNG(img image.Image) ([]byte, error)`	Encode as PNG

Compression

 go
 
func CompressZlib(data []byte) ([]byte, error)

Compresses data with ZLIB (RFC 1950). Use with TransmitDirect() and Compress().