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
74 If true, also free the image data from memory (default: false). Without
75 [~free:true], only placements are removed and the image data can be reused
76 for new placements. *)
77
78(** {1 Animation} *)
79
80val frame :
81 ?image_id:int ->
82 ?image_number:int ->
83 ?format:Kgp_format.t ->
84 ?transmission:Kgp_transmission.t ->
85 ?compression:Kgp_compression.t ->
86 ?width:int ->
87 ?height:int ->
88 ?quiet:Kgp_quiet.t ->
89 frame:Kgp_frame.t ->
90 unit ->
91 t
92(** Transmit animation frame data. *)
93
94val animate :
95 ?image_id:int ->
96 ?image_number:int ->
97 ?quiet:Kgp_quiet.t ->
98 Kgp_animation.t ->
99 t
100(** Control animation playback. *)
101
102val compose :
103 ?image_id:int -> ?image_number:int -> ?quiet:Kgp_quiet.t -> Kgp_compose.t -> t
104(** Compose animation frames. *)
105
106(** {1 Output} *)
107
108val write : Buffer.t -> t -> data:string -> unit
109(** Write the command to a buffer. *)
110
111val to_string : t -> data:string -> string
112(** Convert command to a string. *)
113
114val write_tmux : Buffer.t -> t -> data:string -> unit
115(** Write the command to a buffer with tmux passthrough wrapping.
116
117 If running inside tmux (detected via [TMUX] environment variable), wraps the
118 graphics command in a DCS passthrough sequence. Otherwise, behaves like
119 {!write}. *)
120
121val to_string_tmux : t -> data:string -> string
122(** Convert command to a string with tmux passthrough wrapping.
123
124 If running inside tmux, wraps the output for passthrough. Otherwise, behaves
125 like {!to_string}. *)