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(** Frame Composition
7
8 Operations for compositing rectangular regions between animation frames.
9 This allows building complex frames from simpler components.
10
11 {2 Protocol Overview}
12
13 Frame composition uses action [a=c] to copy a rectangular region from
14 one frame onto another. This is useful for:
15
16 - Building frames from reusable sprite components
17 - Applying partial updates to existing frames
18 - Creating complex animations efficiently
19
20 {2 Coordinate System}
21
22 All coordinates are in pixels, relative to the top-left corner of
23 the respective frame:
24
25 - [source_x], [source_y]: Top-left of rectangle in source frame
26 - [dest_x], [dest_y]: Top-left of destination in target frame
27 - [width], [height]: Size of the rectangle to copy
28
29 If width/height are omitted, the entire source frame is used.
30
31 {2 Composition Mode}
32
33 The [composition] parameter controls blending:
34 - [{`Alpha_blend}]: Standard alpha compositing (default)
35 - [{`Overwrite}]: Direct pixel replacement
36
37 {2 Error Conditions}
38
39 The terminal responds with errors for:
40 - [ENOENT]: Source or destination frame doesn't exist
41 - [EINVAL]: Rectangle out of bounds, or source equals destination
42 with overlapping regions
43 - [ENOSPC]: Not enough storage after composition
44
45 {2 Example}
46
47 {[
48 (* Copy a 32x32 sprite from frame 2 to frame 5 *)
49 let comp = Compose.make
50 ~source_frame:2 ~dest_frame:5
51 ~width:32 ~height:32
52 ~source_x:0 ~source_y:0 (* From top-left of source *)
53 ~dest_x:100 ~dest_y:50 () (* To position in dest *)
54 in
55 Kgp.compose ~image_id:1 comp
56 ]} *)
57
58type t
59(** Composition operation. Opaque type; use {!make} to construct. *)
60
61val make :
62 source_frame:int ->
63 dest_frame:int ->
64 ?width:int ->
65 ?height:int ->
66 ?source_x:int ->
67 ?source_y:int ->
68 ?dest_x:int ->
69 ?dest_y:int ->
70 ?composition:Kgp_composition.t ->
71 unit ->
72 t
73(** Create a composition operation.
74
75 @param source_frame 1-based frame number to copy from. Required.
76 Protocol key: [r].
77 @param dest_frame 1-based frame number to copy onto. Required.
78 Protocol key: [c].
79 @param width Width of rectangle in pixels. Default is full frame.
80 Protocol key: [w].
81 @param height Height of rectangle in pixels. Default is full frame.
82 Protocol key: [h].
83 @param source_x Left edge of source rectangle (default 0).
84 Protocol key: [X].
85 @param source_y Top edge of source rectangle (default 0).
86 Protocol key: [Y].
87 @param dest_x Left edge of destination position (default 0).
88 Protocol key: [x].
89 @param dest_y Top edge of destination position (default 0).
90 Protocol key: [y].
91 @param composition Blending mode. Default is alpha blending.
92 Protocol key: [C]. *)
93
94(** {1 Field Accessors} *)
95
96val source_frame : t -> int
97(** 1-based source frame number. *)
98
99val dest_frame : t -> int
100(** 1-based destination frame number. *)
101
102val width : t -> int option
103(** Width of rectangle in pixels. *)
104
105val height : t -> int option
106(** Height of rectangle in pixels. *)
107
108val source_x : t -> int option
109(** Left edge of source rectangle. *)
110
111val source_y : t -> int option
112(** Top edge of source rectangle. *)
113
114val dest_x : t -> int option
115(** Left edge of destination position. *)
116
117val dest_y : t -> int option
118(** Top edge of destination position. *)
119
120val composition : t -> Kgp_composition.t option
121(** Blending mode for composition. *)