(*---------------------------------------------------------------------------
   Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
   SPDX-License-Identifier: ISC
  ---------------------------------------------------------------------------*)

(** Pixel Composition Mode

    Controls how pixels are blended when compositing images or animation frames.

    {2 Protocol Details}

    The composition mode is specified via the [X] key in the control data (for
    animation frames) or the [C] key (for frame composition operations):
    - Value 0 or omitted: alpha blending (default)
    - Value 1: simple overwrite/replacement

    {2 Alpha Blending}

    [{`Alpha_blend}] performs standard alpha compositing using the source
    pixel's alpha channel. For each pixel:
    - If source alpha is 255 (opaque), source pixel replaces destination
    - If source alpha is 0 (transparent), destination pixel is unchanged
    - Otherwise, colors are blended proportionally

    This mode is essential for:
    - Transparent PNG images
    - Overlaying graphics on backgrounds
    - Anti-aliased edges and text

    {2 Overwrite Mode}

    [{`Overwrite}] simply replaces destination pixels with source pixels,
    ignoring the alpha channel. This is useful for:
    - Performance optimization when transparency isn't needed
    - Replacing rectangular regions entirely
    - Animation frames that completely replace the previous frame *)

type t = [ `Alpha_blend | `Overwrite ]
(** Composition modes.

    - [`Alpha_blend] - Full alpha blending (default). Source pixels are
      composited onto the destination using standard Porter-Duff "over"
      compositing based on the source alpha channel.
    - [`Overwrite] - Simple pixel replacement. Source pixels completely replace
      destination pixels, ignoring alpha values. Faster but no transparency
      support. *)

val to_int : t -> int
(** Convert to protocol integer.

    Returns 0 for [`Alpha_blend] or 1 for [`Overwrite]. These values are used in
    the [X=] or [C=] control data keys. *)