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

(** Kitty Graphics Protocol Commands

    This module provides functions for building and serializing graphics
    protocol commands. *)

type t
(** A graphics protocol command. *)

(** {1 Image Transmission} *)

val transmit :
  ?image_id:int ->
  ?image_number:int ->
  ?format:Kgp_format.t ->
  ?transmission:Kgp_transmission.t ->
  ?compression:Kgp_compression.t ->
  ?width:int ->
  ?height:int ->
  ?size:int ->
  ?offset:int ->
  ?quiet:Kgp_quiet.t ->
  unit ->
  t
(** Transmit image data without displaying. *)

val transmit_and_display :
  ?image_id:int ->
  ?image_number:int ->
  ?format:Kgp_format.t ->
  ?transmission:Kgp_transmission.t ->
  ?compression:Kgp_compression.t ->
  ?width:int ->
  ?height:int ->
  ?size:int ->
  ?offset:int ->
  ?quiet:Kgp_quiet.t ->
  ?placement:Kgp_placement.t ->
  unit ->
  t
(** Transmit image data and display it immediately. *)

val query :
  ?format:Kgp_format.t ->
  ?transmission:Kgp_transmission.t ->
  ?width:int ->
  ?height:int ->
  ?quiet:Kgp_quiet.t ->
  unit ->
  t
(** Query terminal support without storing the image. *)

(** {1 Display} *)

val display :
  ?image_id:int ->
  ?image_number:int ->
  ?placement:Kgp_placement.t ->
  ?quiet:Kgp_quiet.t ->
  unit ->
  t
(** Display a previously transmitted image. *)

(** {1 Deletion} *)

val delete : ?free:bool -> ?quiet:Kgp_quiet.t -> Kgp_delete.t -> t
(** Delete images or placements.

    @param free
      If true, also free the image data from memory (default: false). Without
      [~free:true], only placements are removed and the image data can be reused
      for new placements. *)

(** {1 Animation} *)

val frame :
  ?image_id:int ->
  ?image_number:int ->
  ?format:Kgp_format.t ->
  ?transmission:Kgp_transmission.t ->
  ?compression:Kgp_compression.t ->
  ?width:int ->
  ?height:int ->
  ?quiet:Kgp_quiet.t ->
  frame:Kgp_frame.t ->
  unit ->
  t
(** Transmit animation frame data. *)

val animate :
  ?image_id:int ->
  ?image_number:int ->
  ?quiet:Kgp_quiet.t ->
  Kgp_animation.t ->
  t
(** Control animation playback. *)

val compose :
  ?image_id:int -> ?image_number:int -> ?quiet:Kgp_quiet.t -> Kgp_compose.t -> t
(** Compose animation frames. *)

(** {1 Output} *)

val write : Buffer.t -> t -> data:string -> unit
(** Write the command to a buffer. *)

val to_string : t -> data:string -> string
(** Convert command to a string. *)

val write_tmux : Buffer.t -> t -> data:string -> unit
(** Write the command to a buffer with tmux passthrough wrapping.

    If running inside tmux (detected via [TMUX] environment variable), wraps the
    graphics command in a DCS passthrough sequence. Otherwise, behaves like
    {!write}. *)

val to_string_tmux : t -> data:string -> string
(** Convert command to a string with tmux passthrough wrapping.

    If running inside tmux, wraps the output for passthrough. Otherwise, behaves
    like {!to_string}. *)