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 Placement Configuration
7
8 Configuration for where and how to display images. Placements control
9 cropping, scaling, positioning, and layering of images.
10
11 {2 Protocol Overview}
12
13 When displaying an image, the protocol allows specifying:
14 - Which part of the source image to display (source rectangle)
15 - Where to display it (cell position and pixel offsets)
16 - How large to display it (scaling to cell dimensions)
17 - How it layers with other content (z-index)
18 - Whether it can be referenced via Unicode placeholders
19
20 {2 Source Rectangle}
21
22 The source rectangle specifies which portion of the image to display:
23 - [source_x], [source_y]: Top-left corner in pixels (default: 0, 0)
24 - [source_width], [source_height]: Size in pixels (default: full image)
25
26 The displayed area is the intersection of this rectangle with the actual
27 image bounds. This allows cropping images without modifying the original
28 data.
29
30 {2 Cell-Based Sizing}
31
32 Images are sized in terminal cells:
33 - [columns]: Number of columns to span (width in cells)
34 - [rows]: Number of rows to span (height in cells)
35
36 If both are specified, the source rectangle is scaled to fit. If only one is
37 specified, the other is computed to maintain aspect ratio. If neither is
38 specified, the image is displayed at natural size.
39
40 {2 Pixel Offsets}
41
42 Fine-grained positioning within the starting cell:
43 - [cell_x_offset]: Horizontal offset in pixels from cell left edge
44 - [cell_y_offset]: Vertical offset in pixels from cell top edge
45
46 These offsets must be smaller than the cell dimensions.
47
48 {2 Z-Index Layering}
49
50 The [z_index] controls vertical stacking:
51 - Positive values: drawn above text
52 - Zero: drawn at text level
53 - Negative values: drawn below text
54 - Values < INT32_MIN/2 (-1,073,741,824): drawn under cells with non-default
55 background colors
56
57 Overlapping images with the same z-index are ordered by image ID (lower ID
58 draws first/underneath).
59
60 {2 Placement IDs}
61
62 Each placement can have a unique [placement_id] (1-4294967295). This
63 enables:
64 - Updating a specific placement without affecting others
65 - Deleting specific placements
66 - Moving placements by resending with same image_id + placement_id
67
68 If [placement_id] is 0 or unspecified, each display creates an independent
69 placement. *)
70
71type t
72(** Placement configuration. Opaque type; use {!make} to construct. *)
73
74val make :
75 ?source_x:int ->
76 ?source_y:int ->
77 ?source_width:int ->
78 ?source_height:int ->
79 ?cell_x_offset:int ->
80 ?cell_y_offset:int ->
81 ?columns:int ->
82 ?rows:int ->
83 ?z_index:int ->
84 ?placement_id:int ->
85 ?cursor:Kgp_cursor.t ->
86 ?unicode_placeholder:bool ->
87 unit ->
88 t
89(** Create a placement configuration.
90
91 @param source_x
92 Left edge of source rectangle in pixels (default 0). Protocol key: [x].
93 @param source_y
94 Top edge of source rectangle in pixels (default 0). Protocol key: [y].
95 @param source_width
96 Width of source rectangle in pixels. Default is the full image width.
97 Protocol key: [w].
98 @param source_height
99 Height of source rectangle in pixels. Default is the full image height.
100 Protocol key: [h].
101 @param cell_x_offset
102 X offset within the first cell in pixels. Must be smaller than cell width.
103 Protocol key: [X].
104 @param cell_y_offset
105 Y offset within the first cell in pixels. Must be smaller than cell
106 height. Protocol key: [Y].
107 @param columns
108 Number of columns to display over. Image is scaled to fit. Protocol key:
109 [c].
110 @param rows
111 Number of rows to display over. Image is scaled to fit. Protocol key: [r].
112 @param z_index
113 Stacking order. Positive = above text, negative = below. Protocol key:
114 [z].
115 @param placement_id
116 Unique ID (1-4294967295) for this placement. Allows updating/deleting
117 specific placements. Protocol key: [p].
118 @param cursor Cursor movement policy after display.
119 @param unicode_placeholder
120 If true, creates a virtual (invisible) placement for Unicode placeholder
121 mode. Protocol key: [U=1]. *)
122
123val empty : t
124(** Empty placement with all defaults.
125
126 Equivalent to [make ()]. The image displays at natural size at the current
127 cursor position with default z-index (0). *)
128
129(** {1 Field Accessors} *)
130
131val source_x : t -> int option
132(** Left edge of source rectangle in pixels. *)
133
134val source_y : t -> int option
135(** Top edge of source rectangle in pixels. *)
136
137val source_width : t -> int option
138(** Width of source rectangle in pixels. *)
139
140val source_height : t -> int option
141(** Height of source rectangle in pixels. *)
142
143val cell_x_offset : t -> int option
144(** X offset within the first cell in pixels. *)
145
146val cell_y_offset : t -> int option
147(** Y offset within the first cell in pixels. *)
148
149val columns : t -> int option
150(** Number of columns to display over. *)
151
152val rows : t -> int option
153(** Number of rows to display over. *)
154
155val z_index : t -> int option
156(** Stacking order (z-index). *)
157
158val placement_id : t -> int option
159(** Unique placement identifier. *)
160
161val cursor : t -> Kgp_cursor.t option
162(** Cursor movement policy. *)
163
164val unicode_placeholder : t -> bool
165(** Whether this is a virtual placement for Unicode mode. *)