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