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