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 one
14 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 the
23 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 with
42 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 =
50 Compose.make ~source_frame:2 ~dest_frame:5 ~width:32 ~height:32
51 ~source_x:0 ~source_y:0 (* From top-left of source *)
52 ~dest_x:100 ~dest_y:50 () (* To position in dest *)
53 in
54 Kgp.compose ~image_id:1 comp
55 ]} *)
56
57type t
58(** Composition operation. Opaque type; use {!make} to construct. *)
59
60val make :
61 source_frame:int ->
62 dest_frame:int ->
63 ?width:int ->
64 ?height:int ->
65 ?source_x:int ->
66 ?source_y:int ->
67 ?dest_x:int ->
68 ?dest_y:int ->
69 ?composition:Kgp_composition.t ->
70 unit ->
71 t
72(** Create a composition operation.
73
74 @param source_frame
75 1-based frame number to copy from. Required. Protocol key: [r].
76 @param dest_frame
77 1-based frame number to copy onto. Required. Protocol key: [c].
78 @param width
79 Width of rectangle in pixels. Default is full frame. Protocol key: [w].
80 @param height
81 Height of rectangle in pixels. Default is full frame. Protocol key: [h].
82 @param source_x
83 Left edge of source rectangle (default 0). Protocol key: [X].
84 @param source_y Top edge of source rectangle (default 0). Protocol key: [Y].
85 @param dest_x
86 Left edge of destination position (default 0). Protocol key: [x].
87 @param dest_y
88 Top edge of destination position (default 0). Protocol key: [y].
89 @param composition
90 Blending mode. Default is alpha blending. Protocol key: [C]. *)
91
92(** {1 Field Accessors} *)
93
94val source_frame : t -> int
95(** 1-based source frame number. *)
96
97val dest_frame : t -> int
98(** 1-based destination frame number. *)
99
100val width : t -> int option
101(** Width of rectangle in pixels. *)
102
103val height : t -> int option
104(** Height of rectangle in pixels. *)
105
106val source_x : t -> int option
107(** Left edge of source rectangle. *)
108
109val source_y : t -> int option
110(** Top edge of source rectangle. *)
111
112val dest_x : t -> int option
113(** Left edge of destination position. *)
114
115val dest_y : t -> int option
116(** Top edge of destination position. *)
117
118val composition : t -> Kgp_composition.t option
119(** Blending mode for composition. *)