Kitty Graphics Protocol in OCaml
anil.recoil.org
terminal
graphics
ocaml
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Image Data Format
7
8 Specifies the pixel format of image data being transmitted to the terminal.
9
10 {2 Protocol Details}
11
12 The format is specified via the [f] key in the control data:
13 - [f=24] for RGB (3 bytes per pixel)
14 - [f=32] for RGBA (4 bytes per pixel, default)
15 - [f=100] for PNG
16
17 {2 Raw Pixel Formats}
18
19 For [{`Rgb24}] and [{`Rgba32}], the data consists of raw pixel values in
20 row-major order (left-to-right, top-to-bottom). The image dimensions must be
21 specified via the [width] and [height] parameters.
22
23 - [{`Rgb24}]: 3 bytes per pixel in sRGB color space (red, green, blue)
24 - [{`Rgba32}]: 4 bytes per pixel (red, green, blue, alpha)
25
26 {2 PNG Format}
27
28 For [{`Png}], the data is a complete PNG image. The terminal extracts
29 dimensions from PNG metadata, so [width] and [height] are optional.
30
31 When using both PNG format and zlib compression, you must also specify the
32 [size] parameter with the uncompressed PNG data size. *)
33
34type t = [ `Rgba32 | `Rgb24 | `Png ]
35(** Image data formats.
36
37 - [`Rgba32] - 32-bit RGBA (4 bytes per pixel). Default format. Pixels are
38 ordered red, green, blue, alpha. Alpha of 255 is fully opaque, 0 is fully
39 transparent.
40 - [`Rgb24] - 24-bit RGB (3 bytes per pixel). No alpha channel; pixels are
41 fully opaque. More compact than RGBA for opaque images.
42 - [`Png] - PNG encoded data. The terminal decodes the PNG internally.
43 Supports all PNG color types and bit depths. Most convenient format as
44 dimensions are embedded in the data. *)
45
46val to_int : t -> int
47(** Convert to protocol integer value.
48
49 Returns 24 for [`Rgb24], 32 for [`Rgba32], or 100 for [`Png]. These values
50 are used in the [f=] control data key. *)