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(** Data Compression
7
8 Specifies compression applied to image data before transmission.
9
10 {2 Protocol Details}
11
12 Compression is specified via the [o] key in the control data:
13 - No [o] key means no compression
14 - [o=z] means zlib (RFC 1950 DEFLATE) compression
15
16 Compression is applied to the raw pixel/PNG data {i before} base64
17 encoding. The terminal decompresses after base64 decoding.
18
19 {2 When to Use Compression}
20
21 Zlib compression is beneficial for:
22 - Large images with repetitive patterns
23 - Screenshots and UI graphics
24 - Images with large solid color regions
25
26 It may not help (or could increase size) for:
27 - Already-compressed PNG data
28 - Photographic images with high entropy
29 - Very small images (compression overhead)
30
31 {2 PNG with Compression}
32
33 When using both [{`Png}] format and [{`Zlib}] compression, the [size]
34 parameter must be specified with the original (uncompressed) PNG size.
35 The terminal needs this to allocate the correct buffer for decompression. *)
36
37type t = [ `None | `Zlib ]
38(** Compression options.
39
40 - [`None] - Raw uncompressed data. No [o=] key is sent.
41 - [`Zlib] - RFC 1950 zlib/DEFLATE compression. Data is compressed
42 before base64 encoding and decompressed by the terminal. *)
43
44val to_char : t -> char option
45(** Convert to protocol character.
46
47 Returns [None] for [`None] (no key sent), or [Some 'z'] for [`Zlib].
48 When [Some c] is returned, [o=c] is added to the control data. *)