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 Deletion Target
7
8 Specifies which images or placements to delete.
9
10 {2 Protocol Details}
11
12 Deletion is performed with action [a=d] and the [d] key specifies the
13 deletion type. The [d] key uses single characters:
14
15 {v
16 | Char | Meaning |
17 |------|--------------------------------------------------------|
18 | a/A | All placements visible on screen |
19 | i/I | By image ID (with optional placement ID) |
20 | n/N | By image number (newest with that number) |
21 | c/C | At current cursor position |
22 | p/P | At specific cell coordinates (x, y) |
23 | q/Q | At specific cell with z-index (x, y, z) |
24 | x/X | All in specific column |
25 | y/Y | All in specific row |
26 | z/Z | All with specific z-index |
27 | r/R | By image ID range (min_id to max_id) |
28 | f/F | Animation frames only |
29 v}
30
31 {2 Placements vs Image Data}
32
33 Each deletion type can optionally free image data (controlled by the [~free]
34 parameter in the delete command):
35 - {b Without free}: Removes placements only. The image data remains in
36 memory and can be displayed again later. (Protocol: lowercase char)
37 - {b With free}: Removes placements AND frees the image data. The image
38 cannot be displayed again without retransmitting. (Protocol: uppercase
39 char)
40
41 {2 Placement IDs}
42
43 When deleting by image ID or number, an optional placement ID can be
44 specified to delete only a specific placement. If [None], all placements of
45 that image are deleted.
46
47 {2 Coordinate-Based Deletion}
48
49 For [{`At_cell}] and [{`At_cell_z}], coordinates are 0-based cell positions
50 (not pixel positions). Only placements that intersect the specified cell are
51 deleted.
52
53 {2 Virtual Placements}
54
55 Virtual placements (used for Unicode placeholder mode) are only affected by:
56 [{`By_id}], [{`By_number}], and [{`By_id_range}]. Other deletion commands do
57 not affect virtual placements. *)
58
59type t =
60 [ `All_visible
61 | `By_id of int * int option
62 | `By_number of int * int option
63 | `At_cursor
64 | `At_cell of int * int
65 | `At_cell_z of int * int * int
66 | `By_column of int
67 | `By_row of int
68 | `By_z_index of int
69 | `By_id_range of int * int
70 | `Frames ]
71(** Deletion target specification.
72
73 {b Screen-based:}
74 - [`All_visible] - All placements currently visible on screen
75 - [`At_cursor] - Placements at current cursor position
76 - [`At_cell (x, y)] - Placements intersecting cell at column x, row y
77 - [`At_cell_z (x, y, z)] - Like [`At_cell] but only with z-index z
78 - [`By_column x] - All placements intersecting column x
79 - [`By_row y] - All placements intersecting row y
80 - [`By_z_index z] - All placements with z-index z
81
82 {b ID-based:}
83 - [`By_id (id, placement_id)] - By image ID. If [placement_id] is [Some p],
84 only that specific placement; if [None], all placements.
85 - [`By_number (n, placement_id)] - By image number (newest image with that
86 number). Placement ID works as above.
87 - [`By_id_range (min, max)] - All images with IDs in range [min..max]
88
89 {b Animation:}
90 - [`Frames] - Animation frames only (not the base image)
91
92 Use the [~free] parameter in the delete command to also release image data
93 from memory. *)
94
95val to_char : free:bool -> t -> char
96(** Convert to protocol character for the delete command.
97
98 Returns the character used in the [d=] control data key.
99 @param free
100 If true, returns uppercase (frees data); if false, returns lowercase
101 (keeps data). *)