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