System Interface

Detailed Description

Runtime-swappable function pointers for operations that depend on external implementations (e.g. image decoding).

These are process-global settings that must be configured at startup before any terminal functionality that depends on them is used. Setting these enables various optional features of the terminal. For example, setting a PNG decoder enables PNG image support in the Kitty Graphics Protocol.

Use ghostty_sys_set() with a GhosttySysOption to install or clear an implementation. Passing NULL as the value clears the implementation and disables the corresponding feature.

Example

Defining a PNG decode callback

bool decode_png(void* userdata,
                const GhosttyAllocator* allocator,
                const uint8_t* data,
                size_t data_len,
                GhosttySysImage* out) {
  int* count = (int*)userdata;
  (*count)++;
  printf("  decode_png called (size=%zu, call #%d)\n", data_len, *count);
 
  /* Allocate RGBA pixel data through the provided allocator. */
  const size_t pixel_len = 4;  /* 1x1 RGBA */
  uint8_t* pixels = ghostty_alloc(allocator, pixel_len);
  if (!pixels) return false;
 
  /* Fill with red (R=255, G=0, B=0, A=255). */
  pixels[0] = 255;
  pixels[1] = 0;
  pixels[2] = 0;
  pixels[3] = 255;
 
  out->width = 1;
  out->height = 1;
  out->data = pixels;
  out->data_len = pixel_len;
  return true;
}

Installing the callback and sending a PNG image

int main() {
  /* Install the PNG decoder via the sys interface. */
  int decode_count = 0;
  ghostty_sys_set(GHOSTTY_SYS_OPT_USERDATA, &decode_count);
  ghostty_sys_set(GHOSTTY_SYS_OPT_DECODE_PNG, (const void*)decode_png);
 
  /* Create a terminal with Kitty graphics enabled. */
  GhosttyTerminal terminal = NULL;
  if (ghostty_terminal_new(NULL, &terminal, 80, 24) != GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to create terminal\n");
    return 1;
  }
 
  /* Set cell pixel dimensions so kitty graphics can compute grid sizes. */
  ghostty_terminal_resize(terminal, 80, 24, 8, 16);
 
  /* Set a storage limit to enable Kitty graphics. */
  uint64_t storage_limit = 64 * 1024 * 1024;  /* 64 MiB */
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_KITTY_IMAGE_STORAGE_LIMIT,
                       &storage_limit);
 
  /* Install write_pty to see the protocol response. */
  ghostty_terminal_set(terminal, GHOSTTY_TERMINAL_OPT_WRITE_PTY,
                       (const void*)on_write_pty);
 
  /*
   * Send a Kitty graphics command with an inline 1x1 PNG image.
   *
   * The escape sequence is:
   *   ESC _G a=T,f=100,q=1; <base64 PNG data> ESC \
   *
   * Where:
   *   a=T   — transmit and display
   *   f=100 — PNG format
   *   q=1   — request a response (q=0 would suppress it)
   */
  printf("Sending Kitty graphics PNG image:\n");
  const char* kitty_cmd =
    "\x1b_Ga=T,f=100,q=1;"
    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAA"
    "DUlEQVR4nGP4z8DwHwAFAAH/iZk9HQAAAABJRU5ErkJggg=="
    "\x1b\\";
  ghostty_terminal_vt_write(terminal, (const uint8_t*)kitty_cmd,
                            strlen(kitty_cmd));
 
  printf("PNG decode calls: %d\n", decode_count);
 
  /* Query the kitty graphics storage to verify the image was stored. */
  GhosttyKittyGraphics graphics = NULL;
  if (ghostty_terminal_get(terminal, GHOSTTY_TERMINAL_DATA_KITTY_GRAPHICS,
                           &graphics) != GHOSTTY_SUCCESS || !graphics) {
    fprintf(stderr, "Failed to get kitty graphics storage\n");
    return 1;
  }
  printf("\nKitty graphics storage is available.\n");
 
  /*
   * The storage-wide generation changes on every image/placement
   * mutation. Renderers can compare it against the value from the
   * previous frame: if unchanged, placement iteration and image
   * staleness checks can be skipped entirely.
   */
  uint64_t generation = 0;
  ghostty_kitty_graphics_get(graphics, GHOSTTY_KITTY_GRAPHICS_DATA_GENERATION,
                             &generation);
  printf("Storage generation: %llu\n", (unsigned long long)generation);
 
  /* Iterate placements to find the image ID. */
  GhosttyKittyGraphicsPlacementIterator iter = NULL;
  if (ghostty_kitty_graphics_placement_iterator_new(NULL, &iter) != GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to create placement iterator\n");
    return 1;
  }
  if (ghostty_kitty_graphics_get(graphics,
          GHOSTTY_KITTY_GRAPHICS_DATA_PLACEMENT_ITERATOR, &iter) != GHOSTTY_SUCCESS) {
    fprintf(stderr, "Failed to get placement iterator\n");
    return 1;
  }
 
  int placement_count = 0;
  while (ghostty_kitty_graphics_placement_next(iter)) {
    placement_count++;
    uint32_t image_id = 0;
    uint32_t placement_id = 0;
    bool is_virtual = false;
    int32_t z = 0;
 
    ghostty_kitty_graphics_placement_get_multi(iter, 4,
        (GhosttyKittyGraphicsPlacementData[]){
            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IMAGE_ID,
            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_PLACEMENT_ID,
            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_IS_VIRTUAL,
            GHOSTTY_KITTY_GRAPHICS_PLACEMENT_DATA_Z,
        },
        (void*[]){ &image_id, &placement_id, &is_virtual, &z },
        NULL);
 
    printf("  placement #%d: image_id=%u placement_id=%u virtual=%s z=%d\n",
           placement_count, image_id, placement_id,
           is_virtual ? "true" : "false", z);
 
    /* Look up the image and print its properties. */
    GhosttyKittyGraphicsImage image =
        ghostty_kitty_graphics_image(graphics, image_id);
    if (!image) {
      fprintf(stderr, "Failed to look up image %u\n", image_id);
      return 1;
    }
 
    uint32_t width = 0, height = 0, number = 0;
    GhosttyKittyImageFormat format = 0;
    size_t data_len = 0;
    uint64_t image_generation = 0;
 
    /*
     * The per-image generation changes on every add/replace of this
     * image ID, so it detects retransmissions even when the size and
     * format are unchanged. Texture caches should key staleness on it.
     */
    ghostty_kitty_graphics_image_get_multi(image, 6,
        (GhosttyKittyGraphicsImageData[]){
            GHOSTTY_KITTY_IMAGE_DATA_NUMBER,
            GHOSTTY_KITTY_IMAGE_DATA_WIDTH,
            GHOSTTY_KITTY_IMAGE_DATA_HEIGHT,
            GHOSTTY_KITTY_IMAGE_DATA_FORMAT,
            GHOSTTY_KITTY_IMAGE_DATA_DATA_LEN,
            GHOSTTY_KITTY_IMAGE_DATA_GENERATION,
        },
        (void*[]){ &number, &width, &height, &format, &data_len,
                   &image_generation },
        NULL);
 
    printf("    image: number=%u size=%ux%u format=%d data_len=%zu "
           "generation=%llu\n",
           number, width, height, format, data_len,
           (unsigned long long)image_generation);
 
    /* Compute the rendered pixel size and grid size. */
    uint32_t px_w = 0, px_h = 0, cols = 0, rows = 0;
    if (ghostty_kitty_graphics_placement_pixel_size(iter, image, terminal,
            &px_w, &px_h) == GHOSTTY_SUCCESS) {
      printf("    rendered pixel size: %ux%u\n", px_w, px_h);
    }
    if (ghostty_kitty_graphics_placement_grid_size(iter, image, terminal,
            &cols, &rows) == GHOSTTY_SUCCESS) {
      printf("    grid size: %u cols x %u rows\n", cols, rows);
    }
  }
  printf("Total placements: %d\n", placement_count);
  ghostty_kitty_graphics_placement_iterator_free(iter);
 
  /* Clean up. */
  ghostty_terminal_free(terminal);
 
  /* Clear the sys callbacks. */
  ghostty_sys_set(GHOSTTY_SYS_OPT_DECODE_PNG, NULL);
  ghostty_sys_set(GHOSTTY_SYS_OPT_USERDATA, NULL);
 
  return 0;
}

Typedefs
typedef void(*)	GhosttySysLogFn(void *userdata, GhosttySysLogLevel level, const uint8_t *scope, size_t scope_len, const uint8_t *message, size_t message_len)
typedef bool(*)	GhosttySysDecodePngFn(void *userdata, const GhosttyAllocator *allocator, const uint8_t *data, size_t data_len, GhosttySysImage *out)
typedef bool(*)	GhosttySysRandomSecureFn(void *userdata, uint8_t *buf, size_t len)

Enumerations
enum	GhosttySysLogLevel
enum	GhosttySysOption { GHOSTTY_SYS_OPT_USERDATA = 0 , GHOSTTY_SYS_OPT_DECODE_PNG = 1 , GHOSTTY_SYS_OPT_LOG = 2 , GHOSTTY_SYS_OPT_RANDOM_SECURE = 3 , GHOSTTY_SYS_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }

Functions
GHOSTTY_API GhosttyResult	ghostty_sys_set (GhosttySysOption option, const void *value)
GHOSTTY_API void	ghostty_sys_log_stderr (void *userdata, GhosttySysLogLevel level, const uint8_t *scope, size_t scope_len, const uint8_t *message, size_t message_len)

Data Structures
struct	GhosttySysImage

Typedef Documentation

GhosttySysDecodePngFn

typedef bool(*) GhosttySysDecodePngFn(void *userdata, const GhosttyAllocator *allocator, const uint8_t *data, size_t data_len, GhosttySysImage *out)

Callback type for PNG decoding.

Decodes raw PNG data into RGBA pixels. The output pixel data must be allocated through the provided allocator. The library takes ownership of the buffer and will free it with the same allocator.

Parameters

	userdata	The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
	allocator	The allocator to use for the output pixel buffer
	data	Pointer to the raw PNG data
	data_len	Length of the raw PNG data in bytes
[out]	out	On success, filled with the decoded image

Returns

true on success, false on failure

Definition at line 120 of file sys.h.

GhosttySysLogFn

typedef void(*) GhosttySysLogFn(void *userdata, GhosttySysLogLevel level, const uint8_t *scope, size_t scope_len, const uint8_t *message, size_t message_len)

Callback type for logging.

When installed, internal library log messages are delivered through this callback instead of being discarded. The embedder is responsible for formatting and routing log output.

scope is the log scope name as UTF-8 bytes (e.g. "osc", "kitty"). When the log is unscoped (default scope), scope_len is 0.

All pointer arguments are only valid for the duration of the callback. The callback must be safe to call from any thread.

Parameters

userdata	The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
level	The severity level of the log message
scope	Pointer to the scope name bytes
scope_len	Length of the scope name in bytes
message	Pointer to the log message bytes
message_len	Length of the log message in bytes

Definition at line 98 of file sys.h.

GhosttySysRandomSecureFn

typedef bool(*) GhosttySysRandomSecureFn(void *userdata, uint8_t *buf, size_t len)

Callback type for secure random bytes.

Fills buf with len cryptographically secure random bytes. The library uses this for secrets, so it must be a real CSPRNG (getrandom, arc4random_buf, BCryptGenRandom, crypto.getRandomValues, ...); a predictable source is a security hole.

Parameters

userdata	The userdata pointer set via GHOSTTY_SYS_OPT_USERDATA
buf	Buffer to fill
len	Number of bytes to fill

Returns

true if the buffer was filled, false if no entropy is available

Definition at line 140 of file sys.h.

Enumeration Type Documentation

GhosttySysLogLevel

enum GhosttySysLogLevel

Log severity levels for the log callback.

Definition at line 70 of file sys.h.

GhosttySysOption

enum GhosttySysOption

System option identifiers for ghostty_sys_set().

Enumerator
GHOSTTY_SYS_OPT_USERDATA	Set the userdata pointer passed to all sys callbacks. Input type: void* (or NULL)
GHOSTTY_SYS_OPT_DECODE_PNG	Set the PNG decode function. When set, the terminal can accept PNG images via the Kitty Graphics Protocol. When cleared (NULL value), PNG decoding is unsupported and PNG image data will be rejected. Input type: GhosttySysDecodePngFn (function pointer, or NULL)
GHOSTTY_SYS_OPT_LOG	Set the log callback. When set, internal library log messages are delivered to this callback. When cleared (NULL value), log messages are silently discarded. Use ghostty_sys_log_stderr as a convenience callback that writes formatted messages to stderr. Which log levels are emitted depends on the build mode of the library and is not configurable at runtime. Debug builds emit all levels (debug and above). Release builds emit info and above; debug-level messages are compiled out entirely and will never reach the callback. Input type: GhosttySysLogFn (function pointer, or NULL)
GHOSTTY_SYS_OPT_RANDOM_SECURE	Override the secure random source. By default the library draws secure random bytes from the platform (getrandom or arc4random_buf on POSIX, CNG on Windows). Targets without one, such as wasm32-freestanding, have no default and operations that need entropy fail with GHOSTTY_IO_ERROR until this is set. When set, it is used instead of the platform source on every target. When cleared (NULL value), the platform default is restored. Input type: GhosttySysRandomSecureFn (function pointer, or NULL)

Definition at line 148 of file sys.h.

Function Documentation

ghostty_sys_log_stderr()

GHOSTTY_API void ghostty_sys_log_stderr	(	void *	userdata,
		GhosttySysLogLevel	level,
		const uint8_t *	scope,
		size_t	scope_len,
		const uint8_t *	message,
		size_t	message_len )

Built-in log callback that writes to stderr.

Formats each message as "[level](scope): message\n". Can be passed directly to ghostty_sys_set():

ghostty_sys_set(GHOSTTY_SYS_OPT_LOG, &ghostty_sys_log_stderr);

References ghostty_sys_log_stderr().

Referenced by ghostty_sys_log_stderr().

ghostty_sys_set()

GHOSTTY_API GhosttyResult ghostty_sys_set	(	GhosttySysOption	option,
		const void *	value )

Set a system-level option.

Configures a process-global implementation function. These should be set once at startup before using any terminal functionality that depends on them.

Parameters

option	The option to set
value	Pointer to the value (type depends on the option), or NULL to clear it

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if the option is not recognized

Examples

c-vt-kitty-graphics/src/main.c.

References ghostty_sys_set().

Referenced by ghostty_sys_set().