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