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