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

(** Image Placement Configuration

    Configuration for where and how to display images. Placements control
    cropping, scaling, positioning, and layering of images.

    {2 Protocol Overview}

    When displaying an image, the protocol allows specifying:
    - Which part of the source image to display (source rectangle)
    - Where to display it (cell position and pixel offsets)
    - How large to display it (scaling to cell dimensions)
    - How it layers with other content (z-index)
    - Whether it can be referenced via Unicode placeholders

    {2 Source Rectangle}

    The source rectangle specifies which portion of the image to display:
    - [source_x], [source_y]: Top-left corner in pixels (default: 0, 0)
    - [source_width], [source_height]: Size in pixels (default: full image)

    The displayed area is the intersection of this rectangle with the actual
    image bounds. This allows cropping images without modifying the original
    data.

    {2 Cell-Based Sizing}

    Images are sized in terminal cells:
    - [columns]: Number of columns to span (width in cells)
    - [rows]: Number of rows to span (height in cells)

    If both are specified, the source rectangle is scaled to fit. If only one is
    specified, the other is computed to maintain aspect ratio. If neither is
    specified, the image is displayed at natural size.

    {2 Pixel Offsets}

    Fine-grained positioning within the starting cell:
    - [cell_x_offset]: Horizontal offset in pixels from cell left edge
    - [cell_y_offset]: Vertical offset in pixels from cell top edge

    These offsets must be smaller than the cell dimensions.

    {2 Z-Index Layering}

    The [z_index] controls vertical stacking:
    - Positive values: drawn above text
    - Zero: drawn at text level
    - Negative values: drawn below text
    - Values < INT32_MIN/2 (-1,073,741,824): drawn under cells with non-default
      background colors

    Overlapping images with the same z-index are ordered by image ID (lower ID
    draws first/underneath).

    {2 Placement IDs}

    Each placement can have a unique [placement_id] (1-4294967295). This
    enables:
    - Updating a specific placement without affecting others
    - Deleting specific placements
    - Moving placements by resending with same image_id + placement_id

    If [placement_id] is 0 or unspecified, each display creates an independent
    placement. *)

type t
(** Placement configuration. Opaque type; use {!make} to construct. *)

val make :
  ?source_x:int ->
  ?source_y:int ->
  ?source_width:int ->
  ?source_height:int ->
  ?cell_x_offset:int ->
  ?cell_y_offset:int ->
  ?columns:int ->
  ?rows:int ->
  ?z_index:int ->
  ?placement_id:int ->
  ?cursor:Kgp_cursor.t ->
  ?unicode_placeholder:bool ->
  unit ->
  t
(** Create a placement configuration.

    @param source_x
      Left edge of source rectangle in pixels (default 0). Protocol key: [x].
    @param source_y
      Top edge of source rectangle in pixels (default 0). Protocol key: [y].
    @param source_width
      Width of source rectangle in pixels. Default is the full image width.
      Protocol key: [w].
    @param source_height
      Height of source rectangle in pixels. Default is the full image height.
      Protocol key: [h].
    @param cell_x_offset
      X offset within the first cell in pixels. Must be smaller than cell width.
      Protocol key: [X].
    @param cell_y_offset
      Y offset within the first cell in pixels. Must be smaller than cell
      height. Protocol key: [Y].
    @param columns
      Number of columns to display over. Image is scaled to fit. Protocol key:
      [c].
    @param rows
      Number of rows to display over. Image is scaled to fit. Protocol key: [r].
    @param z_index
      Stacking order. Positive = above text, negative = below. Protocol key:
      [z].
    @param placement_id
      Unique ID (1-4294967295) for this placement. Allows updating/deleting
      specific placements. Protocol key: [p].
    @param cursor Cursor movement policy after display.
    @param unicode_placeholder
      If true, creates a virtual (invisible) placement for Unicode placeholder
      mode. Protocol key: [U=1]. *)

val empty : t
(** Empty placement with all defaults.

    Equivalent to [make ()]. The image displays at natural size at the current
    cursor position with default z-index (0). *)

(** {1 Field Accessors} *)

val source_x : t -> int option
(** Left edge of source rectangle in pixels. *)

val source_y : t -> int option
(** Top edge of source rectangle in pixels. *)

val source_width : t -> int option
(** Width of source rectangle in pixels. *)

val source_height : t -> int option
(** Height of source rectangle in pixels. *)

val cell_x_offset : t -> int option
(** X offset within the first cell in pixels. *)

val cell_y_offset : t -> int option
(** Y offset within the first cell in pixels. *)

val columns : t -> int option
(** Number of columns to display over. *)

val rows : t -> int option
(** Number of rows to display over. *)

val z_index : t -> int option
(** Stacking order (z-index). *)

val placement_id : t -> int option
(** Unique placement identifier. *)

val cursor : t -> Kgp_cursor.t option
(** Cursor movement policy. *)

val unicode_placeholder : t -> bool
(** Whether this is a virtual placement for Unicode mode. *)