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(** Kitty Graphics Protocol Commands
7
8 This module provides functions for building and serializing graphics
9 protocol commands. *)
10
11type t
12(** A graphics protocol command. *)
13
14(** {1 Image Transmission} *)
15
16val transmit :
17 ?image_id:int ->
18 ?image_number:int ->
19 ?format:Kgp_format.t ->
20 ?transmission:Kgp_transmission.t ->
21 ?compression:Kgp_compression.t ->
22 ?width:int ->
23 ?height:int ->
24 ?size:int ->
25 ?offset:int ->
26 ?quiet:Kgp_quiet.t ->
27 unit ->
28 t
29(** Transmit image data without displaying. *)
30
31val transmit_and_display :
32 ?image_id:int ->
33 ?image_number:int ->
34 ?format:Kgp_format.t ->
35 ?transmission:Kgp_transmission.t ->
36 ?compression:Kgp_compression.t ->
37 ?width:int ->
38 ?height:int ->
39 ?size:int ->
40 ?offset:int ->
41 ?quiet:Kgp_quiet.t ->
42 ?placement:Kgp_placement.t ->
43 unit ->
44 t
45(** Transmit image data and display it immediately. *)
46
47val query :
48 ?format:Kgp_format.t ->
49 ?transmission:Kgp_transmission.t ->
50 ?width:int ->
51 ?height:int ->
52 ?quiet:Kgp_quiet.t ->
53 unit ->
54 t
55(** Query terminal support without storing the image. *)
56
57(** {1 Display} *)
58
59val display :
60 ?image_id:int ->
61 ?image_number:int ->
62 ?placement:Kgp_placement.t ->
63 ?quiet:Kgp_quiet.t ->
64 unit ->
65 t
66(** Display a previously transmitted image. *)
67
68(** {1 Deletion} *)
69
70val delete : ?free:bool -> ?quiet:Kgp_quiet.t -> Kgp_delete.t -> t
71(** Delete images or placements.
72
73 @param free If true, also free the image data from memory (default: false).
74 Without [~free:true], only placements are removed and the image data
75 can be reused for new placements. *)
76
77(** {1 Animation} *)
78
79val frame :
80 ?image_id:int ->
81 ?image_number:int ->
82 ?format:Kgp_format.t ->
83 ?transmission:Kgp_transmission.t ->
84 ?compression:Kgp_compression.t ->
85 ?width:int ->
86 ?height:int ->
87 ?quiet:Kgp_quiet.t ->
88 frame:Kgp_frame.t ->
89 unit ->
90 t
91(** Transmit animation frame data. *)
92
93val animate :
94 ?image_id:int ->
95 ?image_number:int ->
96 ?quiet:Kgp_quiet.t ->
97 Kgp_animation.t ->
98 t
99(** Control animation playback. *)
100
101val compose :
102 ?image_id:int ->
103 ?image_number:int ->
104 ?quiet:Kgp_quiet.t ->
105 Kgp_compose.t ->
106 t
107(** Compose animation frames. *)
108
109(** {1 Output} *)
110
111val write : Buffer.t -> t -> data:string -> unit
112(** Write the command to a buffer. *)
113
114val to_string : t -> data:string -> string
115(** Convert command to a string. *)
116
117val write_tmux : Buffer.t -> t -> data:string -> unit
118(** Write the command to a buffer with tmux passthrough wrapping.
119
120 If running inside tmux (detected via [TMUX] environment variable),
121 wraps the graphics command in a DCS passthrough sequence. Otherwise,
122 behaves like {!write}. *)
123
124val to_string_tmux : t -> data:string -> string
125(** Convert command to a string with tmux passthrough wrapping.
126
127 If running inside tmux, wraps the output for passthrough.
128 Otherwise, behaves like {!to_string}. *)