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(** Pixel Composition Mode
7
8 Controls how pixels are blended when compositing images or animation frames.
9
10 {2 Protocol Details}
11
12 The composition mode is specified via the [X] key in the control data (for
13 animation frames) or the [C] key (for frame composition operations):
14 - Value 0 or omitted: alpha blending (default)
15 - Value 1: simple overwrite/replacement
16
17 {2 Alpha Blending}
18
19 [{`Alpha_blend}] performs standard alpha compositing using the source
20 pixel's alpha channel. For each pixel:
21 - If source alpha is 255 (opaque), source pixel replaces destination
22 - If source alpha is 0 (transparent), destination pixel is unchanged
23 - Otherwise, colors are blended proportionally
24
25 This mode is essential for:
26 - Transparent PNG images
27 - Overlaying graphics on backgrounds
28 - Anti-aliased edges and text
29
30 {2 Overwrite Mode}
31
32 [{`Overwrite}] simply replaces destination pixels with source pixels,
33 ignoring the alpha channel. This is useful for:
34 - Performance optimization when transparency isn't needed
35 - Replacing rectangular regions entirely
36 - Animation frames that completely replace the previous frame *)
37
38type t = [ `Alpha_blend | `Overwrite ]
39(** Composition modes.
40
41 - [`Alpha_blend] - Full alpha blending (default). Source pixels are
42 composited onto the destination using standard Porter-Duff "over"
43 compositing based on the source alpha channel.
44 - [`Overwrite] - Simple pixel replacement. Source pixels completely replace
45 destination pixels, ignoring alpha values. Faster but no transparency
46 support. *)
47
48val to_int : t -> int
49(** Convert to protocol integer.
50
51 Returns 0 for [`Alpha_blend] or 1 for [`Overwrite]. These values are used in
52 the [X=] or [C=] control data keys. *)