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 Playback State
7
8 Controls the playback state of animated images.
9
10 {2 Protocol Details}
11
12 The animation state is specified via the [s] key in the control data when
13 using action [a=a]:
14 - [s=1]: stop animation
15 - [s=2]: run in loading mode
16 - [s=3]: run normally
17
18 {2 Animation Modes}
19
20 The protocol supports two animation approaches:
21
22 {b Terminal-driven animation}: The terminal automatically advances frames
23 based on the gap (delay) specified for each frame. Use [{`Run}] or
24 [{`Loading}] states.
25
26 {b Client-driven animation}: The client manually sets the current frame
27 using [Kgp.Animation.set_current_frame]. Use [{`Stop}] state to prevent
28 automatic advancement.
29
30 {2 Stop State}
31
32 [{`Stop}] halts automatic frame advancement. The animation freezes on the
33 current frame. Use this when:
34 - Implementing client-driven animation
35 - Pausing an animation
36 - Displaying a static frame from an animated image
37
38 {2 Loading State}
39
40 [{`Loading}] runs the animation but waits for new frames when reaching the
41 end instead of looping. Use this when:
42 - Streaming animation frames progressively
43 - Building an animation while displaying it
44 - The animation is not yet complete
45
46 {2 Run State}
47
48 [{`Run}] runs the animation normally, looping back to the first frame after
49 the last. The loop count can be controlled via the [loops] parameter in
50 [Kgp.Animation.set_state]. *)
51
52type t = [ `Stop | `Loading | `Run ]
53(** Animation playback states.
54
55 - [`Stop] - Halt animation playback. The animation freezes on the current
56 frame and does not advance automatically.
57 - [`Loading] - Run animation but wait for new frames at end. When the last
58 frame is reached, the animation pauses until more frames are added, then
59 continues.
60 - [`Run] - Run animation normally and loop. After the last frame, playback
61 returns to the first frame (or stops after the specified number of loops).
62*)
63
64val to_int : t -> int
65(** Convert to protocol integer.
66
67 Returns 1 for [`Stop], 2 for [`Loading], or 3 for [`Run]. These values are
68 used in the [s=] control data key. *)