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(** Animation Frame Configuration
7
8 Configuration for adding or editing animation frames. Frames can be
9 full images or partial updates (rectangles), with options for timing
10 and composition.
11
12 {2 Protocol Overview}
13
14 Animations are created by:
15 1. Transmitting a base image (becomes frame 1)
16 2. Adding frames using the frame action ([a=f])
17 3. Controlling playback with animation commands
18
19 Frame numbers are 1-based:
20 - Frame 1: The original/base image
21 - Frame 2+: Added animation frames
22
23 {2 Frame Positioning}
24
25 For partial frame updates, [x] and [y] specify where the new pixel
26 data is placed within the frame canvas:
27 - [x]: Left edge position in pixels (default 0)
28 - [y]: Top edge position in pixels (default 0)
29
30 The frame data dimensions come from the [width] and [height] parameters
31 of the frame command.
32
33 {2 Frame Canvas}
34
35 Each frame needs a background canvas to composite onto. Options:
36
37 {b Solid color background} ([background_color]):
38 Use a 32-bit RGBA color. Format: [0xRRGGBBAA] where AA is alpha.
39 Default is 0 (transparent black).
40
41 {b Copy from existing frame} ([base_frame]):
42 Use another frame as the starting canvas. Specified as 1-based frame
43 number. The base frame's pixels are copied, then new data is composited.
44
45 {2 Editing Existing Frames}
46
47 Instead of creating a new frame, you can edit an existing one:
48 - Set [edit_frame] to the 1-based frame number
49 - The frame itself becomes the canvas
50 - New data is composited onto it
51
52 {2 Frame Timing}
53
54 The [gap_ms] parameter controls the delay before transitioning to
55 the next frame:
56 - Positive value: Delay in milliseconds
57 - Zero: Ignored (keeps existing gap)
58 - Negative value: "Gapless" frame - not displayed, used as a base
59 for other frames
60
61 Default gap for new frames is 40ms. The root frame (frame 1) has
62 a default gap of 0ms.
63
64 {2 Composition Mode}
65
66 The [composition] parameter controls how new pixel data is blended
67 onto the canvas. *)
68
69type t
70(** Animation frame configuration. Opaque type; use {!make} to construct. *)
71
72val make :
73 ?x:int ->
74 ?y:int ->
75 ?base_frame:int ->
76 ?edit_frame:int ->
77 ?gap_ms:int ->
78 ?composition:Kgp_composition.t ->
79 ?background_color:int32 ->
80 unit ->
81 t
82(** Create a frame specification.
83
84 @param x Left edge where frame data is placed in pixels (default 0).
85 Protocol key: [x].
86 @param y Top edge where frame data is placed in pixels (default 0).
87 Protocol key: [y].
88 @param base_frame 1-based frame number to use as background canvas.
89 Frame 1 is the root image. Protocol key: [c].
90 @param edit_frame 1-based frame number to edit instead of creating new.
91 If 0 or unset, a new frame is created. Protocol key: [r].
92 @param gap_ms Delay before next frame in milliseconds. Negative values
93 create gapless frames. Protocol key: [z].
94 @param composition How to blend new pixels onto the canvas.
95 Default is alpha blending. Protocol key: [X].
96 @param background_color 32-bit RGBA background color when not using
97 a base frame. Format: [0xRRGGBBAA]. Protocol key: [Y]. *)
98
99val empty : t
100(** Empty frame spec with all defaults.
101
102 Creates a new frame with transparent black background, composited
103 at position (0, 0) with default timing (40ms gap). *)
104
105(** {1 Field Accessors} *)
106
107val x : t -> int option
108(** Left edge position for frame data in pixels. *)
109
110val y : t -> int option
111(** Top edge position for frame data in pixels. *)
112
113val base_frame : t -> int option
114(** 1-based frame number to use as background canvas. *)
115
116val edit_frame : t -> int option
117(** 1-based frame number being edited (0 or None = new frame). *)
118
119val gap_ms : t -> int option
120(** Delay before next frame in milliseconds. *)
121
122val composition : t -> Kgp_composition.t option
123(** Pixel composition mode. *)
124
125val background_color : t -> int32 option
126(** 32-bit RGBA background color. *)