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(** Kitty Graphics Protocol Unicode Placeholders
7
8 Support for invisible Unicode placeholder characters that encode image
9 position metadata for accessibility and compatibility.
10
11 {2 Image ID Requirements}
12
13 When using unicode placeholders, image IDs must have non-zero bytes in
14 specific positions for correct rendering:
15 - High byte (bits 24-31): encoded as the third combining diacritic
16 - Middle bytes (bits 8-23): encoded in the foreground RGB color
17
18 Use {!next_image_id} to generate IDs that satisfy these requirements. *)
19
20val placeholder_char : Uchar.t
21(** The Unicode placeholder character U+10EEEE. *)
22
23val next_image_id : unit -> int
24(** Generate a random image ID suitable for unicode placeholders.
25
26 The returned ID has non-zero bytes in all required positions:
27 - High byte (bits 24-31) is non-zero
28 - Middle bytes (bits 8-23) are non-zero
29
30 This ensures the foreground color encoding and diacritic encoding work
31 correctly. Uses [Random] internally. *)
32
33val write :
34 Buffer.t ->
35 image_id:int ->
36 ?placement_id:int ->
37 rows:int ->
38 cols:int ->
39 unit ->
40 unit
41(** Write placeholder characters to a buffer.
42
43 @param image_id
44 Should be generated with {!next_image_id} for correct rendering.
45 @param placement_id
46 Optional placement ID for multiple placements of same image.
47 @param rows Number of rows in the placeholder grid.
48 @param cols Number of columns in the placeholder grid. *)
49
50val row_diacritic : int -> Uchar.t
51(** Get the combining diacritic for a row number (0-based). *)
52
53val column_diacritic : int -> Uchar.t
54(** Get the combining diacritic for a column number (0-based). *)
55
56val id_high_byte_diacritic : int -> Uchar.t
57(** Get the diacritic for the high byte of a 32-bit image ID. *)