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
27 actual image bounds. This allows cropping images without modifying
28 the original 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.
37 If only one is specified, the other is computed to maintain aspect ratio.
38 If neither is 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
55 non-default background colors
56
57 Overlapping images with the same z-index are ordered by image ID
58 (lower ID 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
69 independent 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 Left edge of source rectangle in pixels (default 0).
92 Protocol key: [x].
93 @param source_y Top edge of source rectangle in pixels (default 0).
94 Protocol key: [y].
95 @param source_width Width of source rectangle in pixels.
96 Default is the full image width. Protocol key: [w].
97 @param source_height Height of source rectangle in pixels.
98 Default is the full image height. Protocol key: [h].
99 @param cell_x_offset X offset within the first cell in pixels.
100 Must be smaller than cell width. Protocol key: [X].
101 @param cell_y_offset Y offset within the first cell in pixels.
102 Must be smaller than cell height. Protocol key: [Y].
103 @param columns Number of columns to display over. Image is scaled
104 to fit. Protocol key: [c].
105 @param rows Number of rows to display over. Image is scaled to fit.
106 Protocol key: [r].
107 @param z_index Stacking order. Positive = above text, negative = below.
108 Protocol key: [z].
109 @param placement_id Unique ID (1-4294967295) for this placement.
110 Allows updating/deleting specific placements. Protocol key: [p].
111 @param cursor Cursor movement policy after display.
112 @param unicode_placeholder If true, creates a virtual (invisible)
113 placement for Unicode placeholder mode. Protocol key: [U=1]. *)
114
115val empty : t
116(** Empty placement with all defaults.
117
118 Equivalent to [make ()]. The image displays at natural size at the
119 current cursor position with default z-index (0). *)
120
121(** {1 Field Accessors} *)
122
123val source_x : t -> int option
124(** Left edge of source rectangle in pixels. *)
125
126val source_y : t -> int option
127(** Top edge of source rectangle in pixels. *)
128
129val source_width : t -> int option
130(** Width of source rectangle in pixels. *)
131
132val source_height : t -> int option
133(** Height of source rectangle in pixels. *)
134
135val cell_x_offset : t -> int option
136(** X offset within the first cell in pixels. *)
137
138val cell_y_offset : t -> int option
139(** Y offset within the first cell in pixels. *)
140
141val columns : t -> int option
142(** Number of columns to display over. *)
143
144val rows : t -> int option
145(** Number of rows to display over. *)
146
147val z_index : t -> int option
148(** Stacking order (z-index). *)
149
150val placement_id : t -> int option
151(** Unique placement identifier. *)
152
153val cursor : t -> Kgp_cursor.t option
154(** Cursor movement policy. *)
155
156val unicode_placeholder : t -> bool
157(** Whether this is a virtual placement for Unicode mode. *)