commit 53aa0d83159f8d59a1bc7d4da06cf8dc22fb6420 · anil.recoil.org/ocaml-kgp

.gitignore

···

       1
       1
       +
       _build

+11

dune-project

···

       1
       1
       +
       (lang dune 3.20)

     

       2
       2
       +
       (name kitty_graphics)

     

       3
       3
       +
       

     

       4
       4
       +
       (package

     

       5
       5
       +
        (name kitty_graphics)

     

       6
       6
       +
        (synopsis "OCaml implementation of the Kitty terminal graphics protocol")

     

       7
       7
       +
        (description

     

       8
       8
       +
         "A standalone library for rendering images in terminals that support the Kitty graphics protocol. Supports image transmission, display, animation, Unicode placeholders, and terminal capability detection.")

     

       9
       9
       +
        (depends

     

       10
       10
       +
         (ocaml (>= 4.14.0))

     

       11
       11
       +
         base64))

+97

example/anim_test.ml

···

       1
       1
       +
       (* Minimal animation test - shows exact bytes sent *)

     

       2
       2
       +
       

     

       3
       3
       +
       module K = Kitty_graphics

     

       4
       4
       +
       

     

       5
       5
       +
       let solid_color_rgba ~width ~height ~r ~g ~b ~a =

     

       6
       6
       +
         let pixels = Bytes.create (width * height * 4) in

     

       7
       7
       +
         for i = 0 to (width * height) - 1 do

     

       8
       8
       +
           let idx = i * 4 in

     

       9
       9
       +
           Bytes.set pixels idx (Char.chr r);

     

       10
       10
       +
           Bytes.set pixels (idx + 1) (Char.chr g);

     

       11
       11
       +
           Bytes.set pixels (idx + 2) (Char.chr b);

     

       12
       12
       +
           Bytes.set pixels (idx + 3) (Char.chr a)

     

       13
       13
       +
         done;

     

       14
       14
       +
         Bytes.to_string pixels

     

       15
       15
       +
       

     

       16
       16
       +
       let send cmd ~data =

     

       17
       17
       +
         print_string (K.Command.to_string cmd ~data);

     

       18
       18
       +
         flush stdout

     

       19
       19
       +
       

     

       20
       20
       +
       let () =

     

       21
       21
       +
         let width, height = 40, 40 in  (* Smaller for faster testing *)

     

       22
       22
       +
         let image_id = 500 in

     

       23
       23
       +
       

     

       24
       24
       +
         (* Clear any existing image *)

     

       25
       25
       +
         send (K.Command.delete ~quiet:`Errors_only (`All_visible_and_free)) ~data:"";

     

       26
       26
       +
       

     

       27
       27
       +
         (* Step 1: Transmit base frame (red) *)

     

       28
       28
       +
         let red_frame = solid_color_rgba ~width ~height ~r:255 ~g:0 ~b:0 ~a:255 in

     

       29
       29
       +
         send

     

       30
       30
       +
           (K.Command.transmit

     

       31
       31
       +
              ~image_id

     

       32
       32
       +
              ~format:`Rgba32

     

       33
       33
       +
              ~width ~height

     

       34
       34
       +
              ~quiet:`Errors_only

     

       35
       35
       +
              ())

     

       36
       36
       +
           ~data:red_frame;

     

       37
       37
       +
       

     

       38
       38
       +
         (* Step 2: Add frame (blue) *)

     

       39
       39
       +
         let blue_frame = solid_color_rgba ~width ~height ~r:0 ~g:0 ~b:255 ~a:255 in

     

       40
       40
       +
         send

     

       41
       41
       +
           (K.Command.frame

     

       42
       42
       +
              ~image_id

     

       43
       43
       +
              ~format:`Rgba32

     

       44
       44
       +
              ~width ~height

     

       45
       45
       +
              ~frame:(K.Frame.make ~gap_ms:500 ~composition:`Overwrite ())

     

       46
       46
       +
              ~quiet:`Errors_only

     

       47
       47
       +
              ())

     

       48
       48
       +
           ~data:blue_frame;

     

       49
       49
       +
       

     

       50
       50
       +
         (* Step 3: Add frame (green) *)

     

       51
       51
       +
         let green_frame = solid_color_rgba ~width ~height ~r:0 ~g:255 ~b:0 ~a:255 in

     

       52
       52
       +
         send

     

       53
       53
       +
           (K.Command.frame

     

       54
       54
       +
              ~image_id

     

       55
       55
       +
              ~format:`Rgba32

     

       56
       56
       +
              ~width ~height

     

       57
       57
       +
              ~frame:(K.Frame.make ~gap_ms:500 ~composition:`Overwrite ())

     

       58
       58
       +
              ~quiet:`Errors_only

     

       59
       59
       +
              ())

     

       60
       60
       +
           ~data:green_frame;

     

       61
       61
       +
       

     

       62
       62
       +
         (* Step 4: Create placement *)

     

       63
       63
       +
         send

     

       64
       64
       +
           (K.Command.display

     

       65
       65
       +
              ~image_id

     

       66
       66
       +
              ~placement:(K.Placement.make

     

       67
       67
       +
                            ~placement_id:1

     

       68
       68
       +
                            ~cursor:`Static

     

       69
       69
       +
                            ())

     

       70
       70
       +
              ~quiet:`Errors_only

     

       71
       71
       +
              ())

     

       72
       72
       +
           ~data:"";

     

       73
       73
       +
       

     

       74
       74
       +
         (* Step 5: Set root frame gap - IMPORTANT: root frame has no gap by default *)

     

       75
       75
       +
         send

     

       76
       76
       +
           (K.Command.animate ~image_id (K.Animation.set_gap ~frame:1 ~gap_ms:500))

     

       77
       77
       +
           ~data:"";

     

       78
       78
       +
       

     

       79
       79
       +
         (* Step 6: Start animation *)

     

       80
       80
       +
         send

     

       81
       81
       +
           (K.Command.animate ~image_id (K.Animation.set_state ~loops:1 `Run))

     

       82
       82
       +
           ~data:"";

     

       83
       83
       +
       

     

       84
       84
       +
         print_endline "";

     

       85
       85
       +
         print_endline "Animation should be playing (red -> blue -> green).";

     

       86
       86
       +
         print_endline "Press Enter to stop...";

     

       87
       87
       +
         flush stdout;

     

       88
       88
       +
         let _ = read_line () in

     

       89
       89
       +
       

     

       90
       90
       +
         (* Stop animation *)

     

       91
       91
       +
         send

     

       92
       92
       +
           (K.Command.animate ~image_id (K.Animation.set_state `Stop))

     

       93
       93
       +
           ~data:"";

     

       94
       94
       +
       

     

       95
       95
       +
         (* Clean up *)

     

       96
       96
       +
         send (K.Command.delete ~quiet:`Errors_only (`All_visible_and_free)) ~data:"";

     

       97
       97
       +
         print_endline "Done."

+94

example/debug_anim.ml

···

       1
       1
       +
       (* Debug: Output animation escape sequences for comparison with Go *)

     

       2
       2
       +
       

     

       3
       3
       +
       module K = Kitty_graphics

     

       4
       4
       +
       

     

       5
       5
       +
       let solid_color_rgba ~width ~height ~r ~g ~b ~a =

     

       6
       6
       +
         let pixels = Bytes.create (width * height * 4) in

     

       7
       7
       +
         for i = 0 to (width * height) - 1 do

     

       8
       8
       +
           let idx = i * 4 in

     

       9
       9
       +
           Bytes.set pixels idx (Char.chr r);

     

       10
       10
       +
           Bytes.set pixels (idx + 1) (Char.chr g);

     

       11
       11
       +
           Bytes.set pixels (idx + 2) (Char.chr b);

     

       12
       12
       +
           Bytes.set pixels (idx + 3) (Char.chr a)

     

       13
       13
       +
         done;

     

       14
       14
       +
         Bytes.to_string pixels

     

       15
       15
       +
       

     

       16
       16
       +
       let send cmd ~data =

     

       17
       17
       +
         let s = K.Command.to_string cmd ~data in

     

       18
       18
       +
         (* Print escaped version for debugging *)

     

       19
       19
       +
         String.iter (fun c ->

     

       20
       20
       +
           let code = Char.code c in

     

       21
       21
       +
           if code = 27 then print_string "\\x1b"

     

       22
       22
       +
           else if code < 32 || code > 126 then Printf.printf "\\x%02x" code

     

       23
       23
       +
           else print_char c

     

       24
       24
       +
         ) s;

     

       25
       25
       +
         print_newline ()

     

       26
       26
       +
       

     

       27
       27
       +
       let () =

     

       28
       28
       +
         let width, height = 80, 80 in

     

       29
       29
       +
         let image_id = 300 in

     

       30
       30
       +
       

     

       31
       31
       +
         print_endline "=== OCaml Animation Debug ===\n";

     

       32
       32
       +
       

     

       33
       33
       +
         (* Step 1: Transmit base frame *)

     

       34
       34
       +
         print_endline "1. Transmit base frame (a=t):";

     

       35
       35
       +
         let red_frame = solid_color_rgba ~width ~height ~r:255 ~g:0 ~b:0 ~a:255 in

     

       36
       36
       +
         send

     

       37
       37
       +
           (K.Command.transmit

     

       38
       38
       +
              ~image_id

     

       39
       39
       +
              ~format:`Rgba32

     

       40
       40
       +
              ~width ~height

     

       41
       41
       +
              ~quiet:`Errors_only

     

       42
       42
       +
              ())

     

       43
       43
       +
           ~data:red_frame;

     

       44
       44
       +
         print_newline ();

     

       45
       45
       +
       

     

       46
       46
       +
         (* Step 2: Add frame *)

     

       47
       47
       +
         print_endline "2. Add frame (a=f):";

     

       48
       48
       +
         let orange_frame = solid_color_rgba ~width ~height ~r:255 ~g:165 ~b:0 ~a:255 in

     

       49
       49
       +
         send

     

       50
       50
       +
           (K.Command.frame

     

       51
       51
       +
              ~image_id

     

       52
       52
       +
              ~format:`Rgba32

     

       53
       53
       +
              ~width ~height

     

       54
       54
       +
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       55
       55
       +
              ~quiet:`Errors_only

     

       56
       56
       +
              ())

     

       57
       57
       +
           ~data:orange_frame;

     

       58
       58
       +
         print_newline ();

     

       59
       59
       +
       

     

       60
       60
       +
         (* Step 3: Put/display placement *)

     

       61
       61
       +
         print_endline "3. Create placement (a=p):";

     

       62
       62
       +
         send

     

       63
       63
       +
           (K.Command.display

     

       64
       64
       +
              ~image_id

     

       65
       65
       +
              ~placement:(K.Placement.make

     

       66
       66
       +
                            ~placement_id:1

     

       67
       67
       +
                            ~cell_x_offset:0

     

       68
       68
       +
                            ~cell_y_offset:0

     

       69
       69
       +
                            ~cursor:`Static

     

       70
       70
       +
                            ())

     

       71
       71
       +
              ~quiet:`Errors_only

     

       72
       72
       +
              ())

     

       73
       73
       +
           ~data:"";

     

       74
       74
       +
         print_newline ();

     

       75
       75
       +
       

     

       76
       76
       +
         (* Step 4: Set root frame gap *)

     

       77
       77
       +
         print_endline "4. Set root frame gap (a=a,r=1,z=100):";

     

       78
       78
       +
         send

     

       79
       79
       +
           (K.Command.animate ~image_id (K.Animation.set_gap ~frame:1 ~gap_ms:100))

     

       80
       80
       +
           ~data:"";

     

       81
       81
       +
         print_newline ();

     

       82
       82
       +
       

     

       83
       83
       +
         (* Step 5: Animate *)

     

       84
       84
       +
         print_endline "5. Start animation (a=a,s=3,v=1):";

     

       85
       85
       +
         send

     

       86
       86
       +
           (K.Command.animate ~image_id (K.Animation.set_state ~loops:1 `Run))

     

       87
       87
       +
           ~data:"";

     

       88
       88
       +
         print_newline ();

     

       89
       89
       +
       

     

       90
       90
       +
         (* Step 6: Stop animation *)

     

       91
       91
       +
         print_endline "6. Stop animation:";

     

       92
       92
       +
         send

     

       93
       93
       +
           (K.Command.animate ~image_id (K.Animation.set_state `Stop))

     

       94
       94
       +
           ~data:""

+19

example/dune

···

       1
       1
       +
       (executable

     

       2
       2
       +
        (name example)

     

       3
       3
       +
        (libraries kitty_graphics unix))

     

       4
       4
       +
       

     

       5
       5
       +
       (executable

     

       6
       6
       +
        (name debug_anim)

     

       7
       7
       +
        (libraries kitty_graphics))

     

       8
       8
       +
       

     

       9
       9
       +
       (executable

     

       10
       10
       +
        (name test_output)

     

       11
       11
       +
        (libraries kitty_graphics))

     

       12
       12
       +
       

     

       13
       13
       +
       (executable

     

       14
       14
       +
        (name anim_test)

     

       15
       15
       +
        (libraries kitty_graphics))

     

       16
       16
       +
       

     

       17
       17
       +
       (executable

     

       18
       18
       +
        (name tiny_anim)

     

       19
       19
       +
        (libraries kitty_graphics))

+417

example/example.ml

···

       1
       1
       +
       (* Kitty Graphics Protocol Demo - Matching kgp/examples/demo *)

     

       2
       2
       +
       

     

       3
       3
       +
       module K = Kitty_graphics

     

       4
       4
       +
       

     

       5
       5
       +
       (* Helper: Generate a solid color RGBA image *)

     

       6
       6
       +
       let solid_color_rgba ~width ~height ~r ~g ~b ~a =

     

       7
       7
       +
         let pixels = Bytes.create (width * height * 4) in

     

       8
       8
       +
         for i = 0 to (width * height) - 1 do

     

       9
       9
       +
           let idx = i * 4 in

     

       10
       10
       +
           Bytes.set pixels idx (Char.chr r);

     

       11
       11
       +
           Bytes.set pixels (idx + 1) (Char.chr g);

     

       12
       12
       +
           Bytes.set pixels (idx + 2) (Char.chr b);

     

       13
       13
       +
           Bytes.set pixels (idx + 3) (Char.chr a)

     

       14
       14
       +
         done;

     

       15
       15
       +
         Bytes.to_string pixels

     

       16
       16
       +
       

     

       17
       17
       +
       (* Helper: Generate a solid color RGB image (no alpha) *)

     

       18
       18
       +
       let solid_color_rgb ~width ~height ~r ~g ~b =

     

       19
       19
       +
         let pixels = Bytes.create (width * height * 3) in

     

       20
       20
       +
         for i = 0 to (width * height) - 1 do

     

       21
       21
       +
           let idx = i * 3 in

     

       22
       22
       +
           Bytes.set pixels idx (Char.chr r);

     

       23
       23
       +
           Bytes.set pixels (idx + 1) (Char.chr g);

     

       24
       24
       +
           Bytes.set pixels (idx + 2) (Char.chr b)

     

       25
       25
       +
         done;

     

       26
       26
       +
         Bytes.to_string pixels

     

       27
       27
       +
       

     

       28
       28
       +
       (* Helper: Generate a gradient RGBA image *)

     

       29
       29
       +
       let gradient_rgba ~width ~height =

     

       30
       30
       +
         let pixels = Bytes.create (width * height * 4) in

     

       31
       31
       +
         for y = 0 to height - 1 do

     

       32
       32
       +
           for x = 0 to width - 1 do

     

       33
       33
       +
             let idx = (y * width + x) * 4 in

     

       34
       34
       +
             let r = 255 * x / width in

     

       35
       35
       +
             let b = 255 * (width - x) / width in

     

       36
       36
       +
             Bytes.set pixels idx (Char.chr r);

     

       37
       37
       +
             Bytes.set pixels (idx + 1) (Char.chr 128);

     

       38
       38
       +
             Bytes.set pixels (idx + 2) (Char.chr b);

     

       39
       39
       +
             Bytes.set pixels (idx + 3) '\xff'

     

       40
       40
       +
           done

     

       41
       41
       +
         done;

     

       42
       42
       +
         Bytes.to_string pixels

     

       43
       43
       +
       

     

       44
       44
       +
       (* Helper: Read a file *)

     

       45
       45
       +
       let read_file filename =

     

       46
       46
       +
         let ic = open_in_bin filename in

     

       47
       47
       +
         let n = in_channel_length ic in

     

       48
       48
       +
         let s = really_input_string ic n in

     

       49
       49
       +
         close_in ic;

     

       50
       50
       +
         s

     

       51
       51
       +
       

     

       52
       52
       +
       let send cmd ~data =

     

       53
       53
       +
         print_string (K.Command.to_string cmd ~data);

     

       54
       54
       +
         flush stdout

     

       55
       55
       +
       

     

       56
       56
       +
       let wait_for_enter () =

     

       57
       57
       +
         print_string "Press Enter to continue...";

     

       58
       58
       +
         flush stdout;

     

       59
       59
       +
         let _ = read_line () in

     

       60
       60
       +
         print_newline ()

     

       61
       61
       +
       

     

       62
       62
       +
       let clear_screen () =

     

       63
       63
       +
         print_string "\x1b[2J\x1b[H";

     

       64
       64
       +
         for _ = 1 to 5 do print_newline () done;

     

       65
       65
       +
         flush stdout

     

       66
       66
       +
       

     

       67
       67
       +
       let () =

     

       68
       68
       +
         let reader = stdin in

     

       69
       69
       +
         ignore reader;

     

       70
       70
       +
       

     

       71
       71
       +
         clear_screen ();

     

       72
       72
       +
         print_endline "Kitty Graphics Protocol - OCaml Demo";

     

       73
       73
       +
         print_endline "=====================================";

     

       74
       74
       +
         print_newline ();

     

       75
       75
       +
         print_endline "Press Enter to proceed through each demo...";

     

       76
       76
       +
         print_newline ();

     

       77
       77
       +
       

     

       78
       78
       +
         (* Demo 1: Basic formats - PNG *)

     

       79
       79
       +
         clear_screen ();

     

       80
       80
       +
         print_endline "Demo 1: Image Formats - PNG format";

     

       81
       81
       +
         (* Read sf.png and display a small portion as demo *)

     

       82
       82
       +
         (try

     

       83
       83
       +
            let png_data = read_file "sf.png" in

     

       84
       84
       +
            send

     

       85
       85
       +
              (K.Command.transmit_and_display

     

       86
       86
       +
                 ~image_id:1

     

       87
       87
       +
                 ~format:`Png

     

       88
       88
       +
                 ~quiet:`Errors_only

     

       89
       89
       +
                 ~placement:(K.Placement.make ~columns:15 ~rows:8 ())

     

       90
       90
       +
                 ())

     

       91
       91
       +
              ~data:png_data;

     

       92
       92
       +
            print_endline "sf.png displayed using PNG format"

     

       93
       93
       +
          with _ ->

     

       94
       94
       +
            (* Fallback: red square as RGBA *)

     

       95
       95
       +
            let red_data = solid_color_rgba ~width:100 ~height:100 ~r:255 ~g:0 ~b:0 ~a:255 in

     

       96
       96
       +
            send

     

       97
       97
       +
              (K.Command.transmit_and_display

     

       98
       98
       +
                 ~image_id:1

     

       99
       99
       +
                 ~format:`Rgba32

     

       100
       100
       +
                 ~width:100 ~height:100

     

       101
       101
       +
                 ~quiet:`Errors_only

     

       102
       102
       +
                 ())

     

       103
       103
       +
              ~data:red_data;

     

       104
       104
       +
            print_endline "Red square displayed (sf.png not found)");

     

       105
       105
       +
         print_newline ();

     

       106
       106
       +
         wait_for_enter ();

     

       107
       107
       +
       

     

       108
       108
       +
         (* Demo 2: Basic formats - RGBA *)

     

       109
       109
       +
         clear_screen ();

     

       110
       110
       +
         print_endline "Demo 2: Image Formats - RGBA format (32-bit)";

     

       111
       111
       +
         let blue_data = solid_color_rgba ~width:100 ~height:100 ~r:0 ~g:0 ~b:255 ~a:255 in

     

       112
       112
       +
         send

     

       113
       113
       +
           (K.Command.transmit_and_display

     

       114
       114
       +
              ~image_id:2

     

       115
       115
       +
              ~format:`Rgba32

     

       116
       116
       +
              ~width:100 ~height:100

     

       117
       117
       +
              ~quiet:`Errors_only

     

       118
       118
       +
              ())

     

       119
       119
       +
           ~data:blue_data;

     

       120
       120
       +
         print_endline "Blue square displayed using raw RGBA format";

     

       121
       121
       +
         print_newline ();

     

       122
       122
       +
         wait_for_enter ();

     

       123
       123
       +
       

     

       124
       124
       +
         (* Demo 3: Basic formats - RGB *)

     

       125
       125
       +
         clear_screen ();

     

       126
       126
       +
         print_endline "Demo 3: Image Formats - RGB format (24-bit)";

     

       127
       127
       +
         let green_data = solid_color_rgb ~width:100 ~height:100 ~r:0 ~g:255 ~b:0 in

     

       128
       128
       +
         send

     

       129
       129
       +
           (K.Command.transmit_and_display

     

       130
       130
       +
              ~image_id:3

     

       131
       131
       +
              ~format:`Rgb24

     

       132
       132
       +
              ~width:100 ~height:100

     

       133
       133
       +
              ~quiet:`Errors_only

     

       134
       134
       +
              ())

     

       135
       135
       +
           ~data:green_data;

     

       136
       136
       +
         print_endline "Green square displayed using raw RGB format (no alpha channel)";

     

       137
       137
       +
         print_newline ();

     

       138
       138
       +
         wait_for_enter ();

     

       139
       139
       +
       

     

       140
       140
       +
         (* Demo 4: Compression - Note: would need zlib library for actual compression *)

     

       141
       141
       +
         clear_screen ();

     

       142
       142
       +
         print_endline "Demo 4: Large Image (compression requires zlib library)";

     

       143
       143
       +
         let orange_data = solid_color_rgba ~width:200 ~height:200 ~r:255 ~g:165 ~b:0 ~a:255 in

     

       144
       144
       +
         send

     

       145
       145
       +
           (K.Command.transmit_and_display

     

       146
       146
       +
              ~image_id:4

     

       147
       147
       +
              ~format:`Rgba32

     

       148
       148
       +
              ~width:200 ~height:200

     

       149
       149
       +
              ~quiet:`Errors_only

     

       150
       150
       +
              ())

     

       151
       151
       +
           ~data:orange_data;

     

       152
       152
       +
         Printf.printf "Orange square (200x200) - %d bytes uncompressed\n" (String.length orange_data);

     

       153
       153
       +
         print_newline ();

     

       154
       154
       +
         wait_for_enter ();

     

       155
       155
       +
       

     

       156
       156
       +
         (* Demo 5: Load and display external PNG file *)

     

       157
       157
       +
         clear_screen ();

     

       158
       158
       +
         print_endline "Demo 5: Loading external PNG file (sf.png)";

     

       159
       159
       +
         (try

     

       160
       160
       +
            let png_data = read_file "sf.png" in

     

       161
       161
       +
            send

     

       162
       162
       +
              (K.Command.transmit_and_display

     

       163
       163
       +
                 ~image_id:10

     

       164
       164
       +
                 ~format:`Png

     

       165
       165
       +
                 ~quiet:`Errors_only

     

       166
       166
       +
                 ())

     

       167
       167
       +
              ~data:png_data;

     

       168
       168
       +
            print_endline "sf.png loaded and displayed"

     

       169
       169
       +
          with Sys_error msg ->

     

       170
       170
       +
            Printf.printf "sf.png not found: %s\n" msg);

     

       171
       171
       +
         print_newline ();

     

       172
       172
       +
         wait_for_enter ();

     

       173
       173
       +
       

     

       174
       174
       +
         (* Demo 6: Cropping and scaling *)

     

       175
       175
       +
         clear_screen ();

     

       176
       176
       +
         print_endline "Demo 6: Cropping and Scaling - Display part of an image";

     

       177
       177
       +
         let gradient = gradient_rgba ~width:200 ~height:200 in

     

       178
       178
       +
         send

     

       179
       179
       +
           (K.Command.transmit_and_display

     

       180
       180
       +
              ~image_id:20

     

       181
       181
       +
              ~format:`Rgba32

     

       182
       182
       +
              ~width:200 ~height:200

     

       183
       183
       +
              ~placement:(K.Placement.make

     

       184
       184
       +
                            ~source_x:50 ~source_y:50

     

       185
       185
       +
                            ~source_width:100 ~source_height:100

     

       186
       186
       +
                            ~columns:10 ~rows:10

     

       187
       187
       +
                            ())

     

       188
       188
       +
              ~quiet:`Errors_only

     

       189
       189
       +
              ())

     

       190
       190
       +
           ~data:gradient;

     

       191
       191
       +
         print_endline "Cropped to center 100x100 region of a 200x200 gradient";

     

       192
       192
       +
         print_newline ();

     

       193
       193
       +
         wait_for_enter ();

     

       194
       194
       +
       

     

       195
       195
       +
         (* Demo 7: Multiple placements *)

     

       196
       196
       +
         clear_screen ();

     

       197
       197
       +
         print_endline "Demo 7: Multiple Placements - One image, multiple displays";

     

       198
       198
       +
         let cyan_data = solid_color_rgba ~width:80 ~height:80 ~r:0 ~g:255 ~b:255 ~a:255 in

     

       199
       199
       +
         (* Transmit once with an ID *)

     

       200
       200
       +
         send

     

       201
       201
       +
           (K.Command.transmit

     

       202
       202
       +
              ~image_id:100

     

       203
       203
       +
              ~format:`Rgba32

     

       204
       204
       +
              ~width:80 ~height:80

     

       205
       205
       +
              ~quiet:`Errors_only

     

       206
       206
       +
              ())

     

       207
       207
       +
           ~data:cyan_data;

     

       208
       208
       +
         (* Create first placement *)

     

       209
       209
       +
         send

     

       210
       210
       +
           (K.Command.display

     

       211
       211
       +
              ~image_id:100

     

       212
       212
       +
              ~placement:(K.Placement.make ~columns:10 ~rows:5 ())

     

       213
       213
       +
              ~quiet:`Errors_only

     

       214
       214
       +
              ())

     

       215
       215
       +
           ~data:"";

     

       216
       216
       +
         (* Create second placement *)

     

       217
       217
       +
         send

     

       218
       218
       +
           (K.Command.display

     

       219
       219
       +
              ~image_id:100

     

       220
       220
       +
              ~placement:(K.Placement.make ~columns:5 ~rows:3 ())

     

       221
       221
       +
              ~quiet:`Errors_only

     

       222
       222
       +
              ())

     

       223
       223
       +
           ~data:"";

     

       224
       224
       +
         print_newline ();

     

       225
       225
       +
         wait_for_enter ();

     

       226
       226
       +
       

     

       227
       227
       +
         (* Demo 8: Multiple placements with spacing *)

     

       228
       228
       +
         clear_screen ();

     

       229
       229
       +
         print_endline "Demo 8: Multiple Placements with Different Sizes";

     

       230
       230
       +
         print_newline ();

     

       231
       231
       +
         print_endline "Showing same image at different sizes:";

     

       232
       232
       +
         print_newline ();

     

       233
       233
       +
         (* Create a gradient square *)

     

       234
       234
       +
         let grad_small = gradient_rgba ~width:100 ~height:100 in

     

       235
       235
       +
         (* Transmit once *)

     

       236
       236
       +
         send

     

       237
       237
       +
           (K.Command.transmit

     

       238
       238
       +
              ~image_id:160

     

       239
       239
       +
              ~format:`Rgba32

     

       240
       240
       +
              ~width:100 ~height:100

     

       241
       241
       +
              ~quiet:`Errors_only

     

       242
       242
       +
              ())

     

       243
       243
       +
           ~data:grad_small;

     

       244
       244
       +
         (* Place same image three times at different sizes *)

     

       245
       245
       +
         send

     

       246
       246
       +
           (K.Command.display

     

       247
       247
       +
              ~image_id:160

     

       248
       248
       +
              ~placement:(K.Placement.make ~columns:5 ~rows:5 ())

     

       249
       249
       +
              ~quiet:`Errors_only

     

       250
       250
       +
              ())

     

       251
       251
       +
           ~data:"";

     

       252
       252
       +
         print_string "  ";

     

       253
       253
       +
         send

     

       254
       254
       +
           (K.Command.display

     

       255
       255
       +
              ~image_id:160

     

       256
       256
       +
              ~placement:(K.Placement.make ~columns:8 ~rows:8 ())

     

       257
       257
       +
              ~quiet:`Errors_only

     

       258
       258
       +
              ())

     

       259
       259
       +
           ~data:"";

     

       260
       260
       +
         print_string "  ";

     

       261
       261
       +
         send

     

       262
       262
       +
           (K.Command.display

     

       263
       263
       +
              ~image_id:160

     

       264
       264
       +
              ~placement:(K.Placement.make ~columns:12 ~rows:12 ())

     

       265
       265
       +
              ~quiet:`Errors_only

     

       266
       266
       +
              ())

     

       267
       267
       +
           ~data:"";

     

       268
       268
       +
         print_newline ();

     

       269
       269
       +
         print_newline ();

     

       270
       270
       +
         print_endline "Small (5x5 cells), Medium (8x8 cells), Large (12x12 cells)";

     

       271
       271
       +
         print_newline ();

     

       272
       272
       +
         wait_for_enter ();

     

       273
       273
       +
       

     

       274
       274
       +
         (* Demo 9: Z-index layering *)

     

       275
       275
       +
         clear_screen ();

     

       276
       276
       +
         print_endline "Demo 9: Z-Index Layering - Images above/below text";

     

       277
       277
       +
         let bg_data = solid_color_rgba ~width:200 ~height:100 ~r:255 ~g:165 ~b:0 ~a:128 in

     

       278
       278
       +
         send

     

       279
       279
       +
           (K.Command.transmit_and_display

     

       280
       280
       +
              ~image_id:200

     

       281
       281
       +
              ~format:`Rgba32

     

       282
       282
       +
              ~width:200 ~height:100

     

       283
       283
       +
              ~placement:(K.Placement.make ~z_index:(-1) ~cursor:`Static ())

     

       284
       284
       +
              ~quiet:`Errors_only

     

       285
       285
       +
              ())

     

       286
       286
       +
           ~data:bg_data;

     

       287
       287
       +
         print_endline "This orange square should appear behind the text!";

     

       288
       288
       +
         print_newline ();

     

       289
       289
       +
         wait_for_enter ();

     

       290
       290
       +
       

     

       291
       291
       +
         (* Demo 10: Query support *)

     

       292
       292
       +
         clear_screen ();

     

       293
       293
       +
         print_endline "Demo 10: Query Support - Check terminal capabilities";

     

       294
       294
       +
         let query_str = K.Detect.make_query () in

     

       295
       295
       +
         print_string query_str;

     

       296
       296
       +
         flush stdout;

     

       297
       297
       +
         print_endline "(Check if your terminal responds with OK)";

     

       298
       298
       +
         print_newline ();

     

       299
       299
       +
         wait_for_enter ();

     

       300
       300
       +
       

     

       301
       301
       +
         (* Demo 11: Animation - color-changing square *)

     

       302
       302
       +
         clear_screen ();

     

       303
       303
       +
         print_endline "Demo 11: Animation - Color-changing square";

     

       304
       304
       +
         print_endline "Creating animated sequence with 4 colors...";

     

       305
       305
       +
       

     

       306
       306
       +
         let width, height = 80, 80 in

     

       307
       307
       +
         let image_id = 300 in

     

       308
       308
       +
       

     

       309
       309
       +
         (* Create base frame (red) - transmit without displaying *)

     

       310
       310
       +
         let red_frame = solid_color_rgba ~width ~height ~r:255 ~g:0 ~b:0 ~a:255 in

     

       311
       311
       +
         send

     

       312
       312
       +
           (K.Command.transmit

     

       313
       313
       +
              ~image_id

     

       314
       314
       +
              ~format:`Rgba32

     

       315
       315
       +
              ~width ~height

     

       316
       316
       +
              ~quiet:`Errors_only

     

       317
       317
       +
              ())

     

       318
       318
       +
           ~data:red_frame;

     

       319
       319
       +
       

     

       320
       320
       +
         (* Add frames with composition replace *)

     

       321
       321
       +
         let orange_frame = solid_color_rgba ~width ~height ~r:255 ~g:165 ~b:0 ~a:255 in

     

       322
       322
       +
         send

     

       323
       323
       +
           (K.Command.frame

     

       324
       324
       +
              ~image_id

     

       325
       325
       +
              ~format:`Rgba32

     

       326
       326
       +
              ~width ~height

     

       327
       327
       +
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       328
       328
       +
              ~quiet:`Errors_only

     

       329
       329
       +
              ())

     

       330
       330
       +
           ~data:orange_frame;

     

       331
       331
       +
       

     

       332
       332
       +
         let yellow_frame = solid_color_rgba ~width ~height ~r:255 ~g:255 ~b:0 ~a:255 in

     

       333
       333
       +
         send

     

       334
       334
       +
           (K.Command.frame

     

       335
       335
       +
              ~image_id

     

       336
       336
       +
              ~format:`Rgba32

     

       337
       337
       +
              ~width ~height

     

       338
       338
       +
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       339
       339
       +
              ~quiet:`Errors_only

     

       340
       340
       +
              ())

     

       341
       341
       +
           ~data:yellow_frame;

     

       342
       342
       +
       

     

       343
       343
       +
         let green_frame = solid_color_rgba ~width ~height ~r:0 ~g:255 ~b:0 ~a:255 in

     

       344
       344
       +
         send

     

       345
       345
       +
           (K.Command.frame

     

       346
       346
       +
              ~image_id

     

       347
       347
       +
              ~format:`Rgba32

     

       348
       348
       +
              ~width ~height

     

       349
       349
       +
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       350
       350
       +
              ~quiet:`Errors_only

     

       351
       351
       +
              ())

     

       352
       352
       +
           ~data:green_frame;

     

       353
       353
       +
       

     

       354
       354
       +
         (* Create placement and start animation *)

     

       355
       355
       +
         send

     

       356
       356
       +
           (K.Command.display

     

       357
       357
       +
              ~image_id

     

       358
       358
       +
              ~placement:(K.Placement.make

     

       359
       359
       +
                            ~placement_id:1

     

       360
       360
       +
                            ~cell_x_offset:0

     

       361
       361
       +
                            ~cell_y_offset:0

     

       362
       362
       +
                            ~cursor:`Static

     

       363
       363
       +
                            ())

     

       364
       364
       +
              ~quiet:`Errors_only

     

       365
       365
       +
              ())

     

       366
       366
       +
           ~data:"";

     

       367
       367
       +
       

     

       368
       368
       +
         (* Set root frame gap - root frame has no gap by default per Kitty protocol *)

     

       369
       369
       +
         send

     

       370
       370
       +
           (K.Command.animate ~image_id (K.Animation.set_gap ~frame:1 ~gap_ms:100))

     

       371
       371
       +
           ~data:"";

     

       372
       372
       +
       

     

       373
       373
       +
         (* Start animation with infinite looping *)

     

       374
       374
       +
         send

     

       375
       375
       +
           (K.Command.animate ~image_id (K.Animation.set_state ~loops:1 `Run))

     

       376
       376
       +
           ~data:"";

     

       377
       377
       +
       

     

       378
       378
       +
         print_newline ();

     

       379
       379
       +
         print_endline "Animation playing with colors: Red -> Orange -> Yellow -> Green";

     

       380
       380
       +
         print_newline ();

     

       381
       381
       +
       

     

       382
       382
       +
         (* Simulate movement by deleting and recreating placement at different positions *)

     

       383
       383
       +
         for i = 1 to 7 do

     

       384
       384
       +
           Unix.sleepf 0.4;

     

       385
       385
       +
       

     

       386
       386
       +
           (* Delete the current placement *)

     

       387
       387
       +
           send

     

       388
       388
       +
             (K.Command.delete ~quiet:`Errors_only (`By_id (image_id, Some 1)))

     

       389
       389
       +
             ~data:"";

     

       390
       390
       +
       

     

       391
       391
       +
           (* Create new placement at next position *)

     

       392
       392
       +
           send

     

       393
       393
       +
             (K.Command.display

     

       394
       394
       +
                ~image_id

     

       395
       395
       +
                ~placement:(K.Placement.make

     

       396
       396
       +
                              ~placement_id:1

     

       397
       397
       +
                              ~cell_x_offset:(i * 5)

     

       398
       398
       +
                              ~cell_y_offset:0

     

       399
       399
       +
                              ~cursor:`Static

     

       400
       400
       +
                              ())

     

       401
       401
       +
                ~quiet:`Errors_only

     

       402
       402
       +
                ())

     

       403
       403
       +
             ~data:""

     

       404
       404
       +
         done;

     

       405
       405
       +
       

     

       406
       406
       +
         (* Stop the animation *)

     

       407
       407
       +
         send

     

       408
       408
       +
           (K.Command.animate ~image_id (K.Animation.set_state `Stop))

     

       409
       409
       +
           ~data:"";

     

       410
       410
       +
       

     

       411
       411
       +
         print_endline "Animation stopped.";

     

       412
       412
       +
         print_newline ();

     

       413
       413
       +
         print_newline ();

     

       414
       414
       +
         print_endline "Demo complete!";

     

       415
       415
       +
         print_newline ();

     

       416
       416
       +
         print_endline "For more examples, see the library documentation.";

     

       417
       417
       +
         wait_for_enter ()

+59

example/test_output.ml

···

       1
       1
       +
       (* Simple test to show exact escape sequences without data *)

     

       2
       2
       +
       

     

       3
       3
       +
       module K = Kitty_graphics

     

       4
       4
       +
       

     

       5
       5
       +
       let print_escaped s =

     

       6
       6
       +
         String.iter (fun c ->

     

       7
       7
       +
           let code = Char.code c in

     

       8
       8
       +
           if code = 27 then print_string "\\x1b"

     

       9
       9
       +
           else if code < 32 || code > 126 then Printf.printf "\\x%02x" code

     

       10
       10
       +
           else print_char c

     

       11
       11
       +
         ) s;

     

       12
       12
       +
         print_newline ()

     

       13
       13
       +
       

     

       14
       14
       +
       let () =

     

       15
       15
       +
         let image_id = 300 in

     

       16
       16
       +
         let width, height = 80, 80 in

     

       17
       17
       +
       

     

       18
       18
       +
         print_endline "=== Animation Escape Sequences (no data) ===\n";

     

       19
       19
       +
       

     

       20
       20
       +
         (* 1. Transmit base frame (no data for testing) *)

     

       21
       21
       +
         print_endline "1. Transmit (a=t):";

     

       22
       22
       +
         let cmd1 = K.Command.transmit

     

       23
       23
       +
           ~image_id ~format:`Rgba32 ~width ~height ~quiet:`Errors_only () in

     

       24
       24
       +
         print_escaped (K.Command.to_string cmd1 ~data:"");

     

       25
       25
       +
       

     

       26
       26
       +
         (* 2. Frame command *)

     

       27
       27
       +
         print_endline "\n2. Frame (a=f):";

     

       28
       28
       +
         let cmd2 = K.Command.frame

     

       29
       29
       +
           ~image_id ~format:`Rgba32 ~width ~height

     

       30
       30
       +
           ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       31
       31
       +
           ~quiet:`Errors_only () in

     

       32
       32
       +
         print_escaped (K.Command.to_string cmd2 ~data:"");

     

       33
       33
       +
       

     

       34
       34
       +
         (* 3. Put/display command *)

     

       35
       35
       +
         print_endline "\n3. Display/Put (a=p):";

     

       36
       36
       +
         let cmd3 = K.Command.display

     

       37
       37
       +
           ~image_id

     

       38
       38
       +
           ~placement:(K.Placement.make

     

       39
       39
       +
             ~placement_id:1

     

       40
       40
       +
             ~cell_x_offset:0

     

       41
       41
       +
             ~cell_y_offset:0

     

       42
       42
       +
             ~cursor:`Static ())

     

       43
       43
       +
           ~quiet:`Errors_only () in

     

       44
       44
       +
         print_escaped (K.Command.to_string cmd3 ~data:"");

     

       45
       45
       +
       

     

       46
       46
       +
         (* 4. Set root frame gap - IMPORTANT for animation! *)

     

       47
       47
       +
         print_endline "\n4. Set root frame gap (a=a, r=1, z=100):";

     

       48
       48
       +
         let cmd4 = K.Command.animate ~image_id (K.Animation.set_gap ~frame:1 ~gap_ms:100) in

     

       49
       49
       +
         print_escaped (K.Command.to_string cmd4 ~data:"");

     

       50
       50
       +
       

     

       51
       51
       +
         (* 5. Animate - start *)

     

       52
       52
       +
         print_endline "\n5. Animate start (a=a, s=3, v=1):";

     

       53
       53
       +
         let cmd5 = K.Command.animate ~image_id (K.Animation.set_state ~loops:1 `Run) in

     

       54
       54
       +
         print_escaped (K.Command.to_string cmd5 ~data:"");

     

       55
       55
       +
       

     

       56
       56
       +
         (* 6. Animate - stop *)

     

       57
       57
       +
         print_endline "\n6. Animate stop (a=a, s=1):";

     

       58
       58
       +
         let cmd6 = K.Command.animate ~image_id (K.Animation.set_state `Stop) in

     

       59
       59
       +
         print_escaped (K.Command.to_string cmd6 ~data:"")

+108

example/tiny_anim.ml

···

       1
       1
       +
       (* Tiny animation test - no chunking needed *)

     

       2
       2
       +
       (* Uses 20x20 images which are ~1067 bytes base64 (well under 4096) *)

     

       3
       3
       +
       

     

       4
       4
       +
       module K = Kitty_graphics

     

       5
       5
       +
       

     

       6
       6
       +
       let solid_color_rgba ~width ~height ~r ~g ~b ~a =

     

       7
       7
       +
         let pixels = Bytes.create (width * height * 4) in

     

       8
       8
       +
         for i = 0 to (width * height) - 1 do

     

       9
       9
       +
           let idx = i * 4 in

     

       10
       10
       +
           Bytes.set pixels idx (Char.chr r);

     

       11
       11
       +
           Bytes.set pixels (idx + 1) (Char.chr g);

     

       12
       12
       +
           Bytes.set pixels (idx + 2) (Char.chr b);

     

       13
       13
       +
           Bytes.set pixels (idx + 3) (Char.chr a)

     

       14
       14
       +
         done;

     

       15
       15
       +
         Bytes.to_string pixels

     

       16
       16
       +
       

     

       17
       17
       +
       let send cmd ~data =

     

       18
       18
       +
         print_string (K.Command.to_string cmd ~data);

     

       19
       19
       +
         flush stdout

     

       20
       20
       +
       

     

       21
       21
       +
       let () =

     

       22
       22
       +
         (* Use 20x20 to avoid chunking: 20*20*4 = 1600 bytes, base64 ~2134 bytes *)

     

       23
       23
       +
         let width, height = 20, 20 in

     

       24
       24
       +
         let image_id = 999 in

     

       25
       25
       +
       

     

       26
       26
       +
         (* Clear any existing images *)

     

       27
       27
       +
         send (K.Command.delete ~quiet:`Errors_only (`All_visible_and_free)) ~data:"";

     

       28
       28
       +
       

     

       29
       29
       +
         (* Step 1: Transmit base frame (red) - matching Go's sequence *)

     

       30
       30
       +
         let red_frame = solid_color_rgba ~width ~height ~r:255 ~g:0 ~b:0 ~a:255 in

     

       31
       31
       +
         send

     

       32
       32
       +
           (K.Command.transmit

     

       33
       33
       +
              ~image_id

     

       34
       34
       +
              ~format:`Rgba32

     

       35
       35
       +
              ~width ~height

     

       36
       36
       +
              ~quiet:`Errors_only

     

       37
       37
       +
              ())

     

       38
       38
       +
           ~data:red_frame;

     

       39
       39
       +
       

     

       40
       40
       +
         (* Step 2: Add frame (orange) with 100ms gap - like Go *)

     

       41
       41
       +
         let orange_frame = solid_color_rgba ~width ~height ~r:255 ~g:165 ~b:0 ~a:255 in

     

       42
       42
       +
         send

     

       43
       43
       +
           (K.Command.frame

     

       44
       44
       +
              ~image_id

     

       45
       45
       +
              ~format:`Rgba32

     

       46
       46
       +
              ~width ~height

     

       47
       47
       +
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       48
       48
       +
              ~quiet:`Errors_only

     

       49
       49
       +
              ())

     

       50
       50
       +
           ~data:orange_frame;

     

       51
       51
       +
       

     

       52
       52
       +
         (* Step 3: Add frame (yellow) *)

     

       53
       53
       +
         let yellow_frame = solid_color_rgba ~width ~height ~r:255 ~g:255 ~b:0 ~a:255 in

     

       54
       54
       +
         send

     

       55
       55
       +
           (K.Command.frame

     

       56
       56
       +
              ~image_id

     

       57
       57
       +
              ~format:`Rgba32

     

       58
       58
       +
              ~width ~height

     

       59
       59
       +
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       60
       60
       +
              ~quiet:`Errors_only

     

       61
       61
       +
              ())

     

       62
       62
       +
           ~data:yellow_frame;

     

       63
       63
       +
       

     

       64
       64
       +
         (* Step 4: Add frame (green) *)

     

       65
       65
       +
         let green_frame = solid_color_rgba ~width ~height ~r:0 ~g:255 ~b:0 ~a:255 in

     

       66
       66
       +
         send

     

       67
       67
       +
           (K.Command.frame

     

       68
       68
       +
              ~image_id

     

       69
       69
       +
              ~format:`Rgba32

     

       70
       70
       +
              ~width ~height

     

       71
       71
       +
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       72
       72
       +
              ~quiet:`Errors_only

     

       73
       73
       +
              ())

     

       74
       74
       +
           ~data:green_frame;

     

       75
       75
       +
       

     

       76
       76
       +
         (* Step 5: Create placement - exactly like Go *)

     

       77
       77
       +
         send

     

       78
       78
       +
           (K.Command.display

     

       79
       79
       +
              ~image_id

     

       80
       80
       +
              ~placement:(K.Placement.make

     

       81
       81
       +
                            ~placement_id:1

     

       82
       82
       +
                            ~cell_x_offset:0

     

       83
       83
       +
                            ~cell_y_offset:0

     

       84
       84
       +
                            ~cursor:`Static

     

       85
       85
       +
                            ())

     

       86
       86
       +
              ~quiet:`Errors_only

     

       87
       87
       +
              ())

     

       88
       88
       +
           ~data:"";

     

       89
       89
       +
       

     

       90
       90
       +
         (* Step 6: Start animation - exactly like Go (NO root frame gap) *)

     

       91
       91
       +
         send

     

       92
       92
       +
           (K.Command.animate ~image_id (K.Animation.set_state ~loops:1 `Run))

     

       93
       93
       +
           ~data:"";

     

       94
       94
       +
       

     

       95
       95
       +
         print_endline "";

     

       96
       96
       +
         print_endline "Tiny animation (20x20) - Red -> Orange -> Yellow -> Green";

     

       97
       97
       +
         print_endline "This uses no chunking. Press Enter to stop...";

     

       98
       98
       +
         flush stdout;

     

       99
       99
       +
         let _ = read_line () in

     

       100
       100
       +
       

     

       101
       101
       +
         (* Stop animation *)

     

       102
       102
       +
         send

     

       103
       103
       +
           (K.Command.animate ~image_id (K.Animation.set_state `Stop))

     

       104
       104
       +
           ~data:"";

     

       105
       105
       +
       

     

       106
       106
       +
         (* Clean up *)

     

       107
       107
       +
         send (K.Command.delete ~quiet:`Errors_only (`All_visible_and_free)) ~data:"";

     

       108
       108
       +
         print_endline "Done."

lib/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (name kitty_graphics)

     

       3
       3
       +
        (public_name kitty_graphics)

     

       4
       4
       +
        (libraries base64))

+687

lib/kitty_graphics.ml

···

       1
       1
       +
       (* Kitty Terminal Graphics Protocol - Implementation *)

     

       2
       2
       +
       

     

       3
       3
       +
       (* Polymorphic variant types *)

     

       4
       4
       +
       type format = [ `Rgba32 | `Rgb24 | `Png ]

     

       5
       5
       +
       type transmission = [ `Direct | `File | `Tempfile ]

     

       6
       6
       +
       type compression = [ `None | `Zlib ]

     

       7
       7
       +
       type quiet = [ `Noisy | `Errors_only | `Silent ]

     

       8
       8
       +
       type cursor = [ `Move | `Static ]

     

       9
       9
       +
       type composition = [ `Alpha_blend | `Overwrite ]

     

       10
       10
       +
       

     

       11
       11
       +
       type delete =

     

       12
       12
       +
         [ `All_visible

     

       13
       13
       +
         | `All_visible_and_free

     

       14
       14
       +
         | `By_id of int * int option

     

       15
       15
       +
         | `By_id_and_free of int * int option

     

       16
       16
       +
         | `By_number of int * int option

     

       17
       17
       +
         | `By_number_and_free of int * int option

     

       18
       18
       +
         | `At_cursor

     

       19
       19
       +
         | `At_cursor_and_free

     

       20
       20
       +
         | `At_cell of int * int

     

       21
       21
       +
         | `At_cell_and_free of int * int

     

       22
       22
       +
         | `At_cell_z of int * int * int

     

       23
       23
       +
         | `At_cell_z_and_free of int * int * int

     

       24
       24
       +
         | `By_column of int

     

       25
       25
       +
         | `By_column_and_free of int

     

       26
       26
       +
         | `By_row of int

     

       27
       27
       +
         | `By_row_and_free of int

     

       28
       28
       +
         | `By_z_index of int

     

       29
       29
       +
         | `By_z_index_and_free of int

     

       30
       30
       +
         | `By_id_range of int * int

     

       31
       31
       +
         | `By_id_range_and_free of int * int

     

       32
       32
       +
         | `Frames

     

       33
       33
       +
         | `Frames_and_free ]

     

       34
       34
       +
       

     

       35
       35
       +
       type animation_state = [ `Stop | `Loading | `Run ]

     

       36
       36
       +
       

     

       37
       37
       +
       (* Modules re-export the types with conversion functions *)

     

       38
       38
       +
       module Format = struct

     

       39
       39
       +
         type t = format

     

       40
       40
       +
       

     

       41
       41
       +
         let to_int : t -> int = function

     

       42
       42
       +
           | `Rgba32 -> 32

     

       43
       43
       +
           | `Rgb24 -> 24

     

       44
       44
       +
           | `Png -> 100

     

       45
       45
       +
       end

     

       46
       46
       +
       

     

       47
       47
       +
       module Transmission = struct

     

       48
       48
       +
         type t = transmission

     

       49
       49
       +
       

     

       50
       50
       +
         let to_char : t -> char = function

     

       51
       51
       +
           | `Direct -> 'd'

     

       52
       52
       +
           | `File -> 'f'

     

       53
       53
       +
           | `Tempfile -> 't'

     

       54
       54
       +
       end

     

       55
       55
       +
       

     

       56
       56
       +
       module Compression = struct

     

       57
       57
       +
         type t = compression

     

       58
       58
       +
       

     

       59
       59
       +
         let to_char : t -> char option = function

     

       60
       60
       +
           | `None -> None

     

       61
       61
       +
           | `Zlib -> Some 'z'

     

       62
       62
       +
       end

     

       63
       63
       +
       

     

       64
       64
       +
       module Quiet = struct

     

       65
       65
       +
         type t = quiet

     

       66
       66
       +
       

     

       67
       67
       +
         let to_int : t -> int = function

     

       68
       68
       +
           | `Noisy -> 0

     

       69
       69
       +
           | `Errors_only -> 1

     

       70
       70
       +
           | `Silent -> 2

     

       71
       71
       +
       end

     

       72
       72
       +
       

     

       73
       73
       +
       module Cursor = struct

     

       74
       74
       +
         type t = cursor

     

       75
       75
       +
       

     

       76
       76
       +
         let to_int : t -> int = function

     

       77
       77
       +
           | `Move -> 0

     

       78
       78
       +
           | `Static -> 1

     

       79
       79
       +
       end

     

       80
       80
       +
       

     

       81
       81
       +
       module Composition = struct

     

       82
       82
       +
         type t = composition

     

       83
       83
       +
       

     

       84
       84
       +
         let to_int : t -> int = function

     

       85
       85
       +
           | `Alpha_blend -> 0

     

       86
       86
       +
           | `Overwrite -> 1

     

       87
       87
       +
       end

     

       88
       88
       +
       

     

       89
       89
       +
       module Delete = struct

     

       90
       90
       +
         type t = delete

     

       91
       91
       +
       end

     

       92
       92
       +
       

     

       93
       93
       +
       module Placement = struct

     

       94
       94
       +
         type t = {

     

       95
       95
       +
           source_x : int option;

     

       96
       96
       +
           source_y : int option;

     

       97
       97
       +
           source_width : int option;

     

       98
       98
       +
           source_height : int option;

     

       99
       99
       +
           cell_x_offset : int option;

     

       100
       100
       +
           cell_y_offset : int option;

     

       101
       101
       +
           columns : int option;

     

       102
       102
       +
           rows : int option;

     

       103
       103
       +
           z_index : int option;

     

       104
       104
       +
           placement_id : int option;

     

       105
       105
       +
           cursor : cursor option;

     

       106
       106
       +
           unicode_placeholder : bool;

     

       107
       107
       +
         }

     

       108
       108
       +
       

     

       109
       109
       +
         let empty =

     

       110
       110
       +
           {

     

       111
       111
       +
             source_x = None;

     

       112
       112
       +
             source_y = None;

     

       113
       113
       +
             source_width = None;

     

       114
       114
       +
             source_height = None;

     

       115
       115
       +
             cell_x_offset = None;

     

       116
       116
       +
             cell_y_offset = None;

     

       117
       117
       +
             columns = None;

     

       118
       118
       +
             rows = None;

     

       119
       119
       +
             z_index = None;

     

       120
       120
       +
             placement_id = None;

     

       121
       121
       +
             cursor = None;

     

       122
       122
       +
             unicode_placeholder = false;

     

       123
       123
       +
           }

     

       124
       124
       +
       

     

       125
       125
       +
         let make ?source_x ?source_y ?source_width ?source_height ?cell_x_offset

     

       126
       126
       +
             ?cell_y_offset ?columns ?rows ?z_index ?placement_id ?cursor

     

       127
       127
       +
             ?(unicode_placeholder = false) () =

     

       128
       128
       +
           {

     

       129
       129
       +
             source_x;

     

       130
       130
       +
             source_y;

     

       131
       131
       +
             source_width;

     

       132
       132
       +
             source_height;

     

       133
       133
       +
             cell_x_offset;

     

       134
       134
       +
             cell_y_offset;

     

       135
       135
       +
             columns;

     

       136
       136
       +
             rows;

     

       137
       137
       +
             z_index;

     

       138
       138
       +
             placement_id;

     

       139
       139
       +
             cursor;

     

       140
       140
       +
             unicode_placeholder;

     

       141
       141
       +
           }

     

       142
       142
       +
       end

     

       143
       143
       +
       

     

       144
       144
       +
       module Frame = struct

     

       145
       145
       +
         type t = {

     

       146
       146
       +
           x : int option;

     

       147
       147
       +
           y : int option;

     

       148
       148
       +
           base_frame : int option;

     

       149
       149
       +
           edit_frame : int option;

     

       150
       150
       +
           gap_ms : int option;

     

       151
       151
       +
           composition : composition option;

     

       152
       152
       +
           background_color : int32 option;

     

       153
       153
       +
         }

     

       154
       154
       +
       

     

       155
       155
       +
         let empty =

     

       156
       156
       +
           {

     

       157
       157
       +
             x = None;

     

       158
       158
       +
             y = None;

     

       159
       159
       +
             base_frame = None;

     

       160
       160
       +
             edit_frame = None;

     

       161
       161
       +
             gap_ms = None;

     

       162
       162
       +
             composition = None;

     

       163
       163
       +
             background_color = None;

     

       164
       164
       +
           }

     

       165
       165
       +
       

     

       166
       166
       +
         let make ?x ?y ?base_frame ?edit_frame ?gap_ms ?composition ?background_color

     

       167
       167
       +
             () =

     

       168
       168
       +
           { x; y; base_frame; edit_frame; gap_ms; composition; background_color }

     

       169
       169
       +
       end

     

       170
       170
       +
       

     

       171
       171
       +
       module Animation = struct

     

       172
       172
       +
         type state = animation_state

     

       173
       173
       +
       

     

       174
       174
       +
         type t =

     

       175
       175
       +
           [ `Set_state of state * int option

     

       176
       176
       +
           | `Set_gap of int * int

     

       177
       177
       +
           | `Set_current of int ]

     

       178
       178
       +
       

     

       179
       179
       +
         let set_state ?loops state = `Set_state (state, loops)

     

       180
       180
       +
         let set_gap ~frame ~gap_ms = `Set_gap (frame, gap_ms)

     

       181
       181
       +
         let set_current_frame frame = `Set_current frame

     

       182
       182
       +
       end

     

       183
       183
       +
       

     

       184
       184
       +
       module Compose = struct

     

       185
       185
       +
         type t = {

     

       186
       186
       +
           source_frame : int;

     

       187
       187
       +
           dest_frame : int;

     

       188
       188
       +
           width : int option;

     

       189
       189
       +
           height : int option;

     

       190
       190
       +
           source_x : int option;

     

       191
       191
       +
           source_y : int option;

     

       192
       192
       +
           dest_x : int option;

     

       193
       193
       +
           dest_y : int option;

     

       194
       194
       +
           composition : composition option;

     

       195
       195
       +
         }

     

       196
       196
       +
       

     

       197
       197
       +
         let make ~source_frame ~dest_frame ?width ?height ?source_x ?source_y ?dest_x

     

       198
       198
       +
             ?dest_y ?composition () =

     

       199
       199
       +
           {

     

       200
       200
       +
             source_frame;

     

       201
       201
       +
             dest_frame;

     

       202
       202
       +
             width;

     

       203
       203
       +
             height;

     

       204
       204
       +
             source_x;

     

       205
       205
       +
             source_y;

     

       206
       206
       +
             dest_x;

     

       207
       207
       +
             dest_y;

     

       208
       208
       +
             composition;

     

       209
       209
       +
           }

     

       210
       210
       +
       end

     

       211
       211
       +
       

     

       212
       212
       +
       module Command = struct

     

       213
       213
       +
         type action =

     

       214
       214
       +
           [ `Transmit

     

       215
       215
       +
           | `Transmit_and_display

     

       216
       216
       +
           | `Query

     

       217
       217
       +
           | `Display

     

       218
       218
       +
           | `Delete

     

       219
       219
       +
           | `Frame

     

       220
       220
       +
           | `Animate

     

       221
       221
       +
           | `Compose ]

     

       222
       222
       +
       

     

       223
       223
       +
         type t = {

     

       224
       224
       +
           action : action;

     

       225
       225
       +
           format : format option;

     

       226
       226
       +
           transmission : transmission option;

     

       227
       227
       +
           compression : compression option;

     

       228
       228
       +
           width : int option;

     

       229
       229
       +
           height : int option;

     

       230
       230
       +
           size : int option;

     

       231
       231
       +
           offset : int option;

     

       232
       232
       +
           quiet : quiet option;

     

       233
       233
       +
           image_id : int option;

     

       234
       234
       +
           image_number : int option;

     

       235
       235
       +
           placement : Placement.t option;

     

       236
       236
       +
           delete : delete option;

     

       237
       237
       +
           frame : Frame.t option;

     

       238
       238
       +
           animation : Animation.t option;

     

       239
       239
       +
           compose : Compose.t option;

     

       240
       240
       +
         }

     

       241
       241
       +
       

     

       242
       242
       +
         let make action =

     

       243
       243
       +
           {

     

       244
       244
       +
             action;

     

       245
       245
       +
             format = None;

     

       246
       246
       +
             transmission = None;

     

       247
       247
       +
             compression = None;

     

       248
       248
       +
             width = None;

     

       249
       249
       +
             height = None;

     

       250
       250
       +
             size = None;

     

       251
       251
       +
             offset = None;

     

       252
       252
       +
             quiet = None;

     

       253
       253
       +
             image_id = None;

     

       254
       254
       +
             image_number = None;

     

       255
       255
       +
             placement = None;

     

       256
       256
       +
             delete = None;

     

       257
       257
       +
             frame = None;

     

       258
       258
       +
             animation = None;

     

       259
       259
       +
             compose = None;

     

       260
       260
       +
           }

     

       261
       261
       +
       

     

       262
       262
       +
         let transmit ?image_id ?image_number ?format ?transmission ?compression ?width

     

       263
       263
       +
             ?height ?size ?offset ?quiet () =

     

       264
       264
       +
           {

     

       265
       265
       +
             (make `Transmit) with

     

       266
       266
       +
             image_id;

     

       267
       267
       +
             image_number;

     

       268
       268
       +
             format;

     

       269
       269
       +
             transmission;

     

       270
       270
       +
             compression;

     

       271
       271
       +
             width;

     

       272
       272
       +
             height;

     

       273
       273
       +
             size;

     

       274
       274
       +
             offset;

     

       275
       275
       +
             quiet;

     

       276
       276
       +
           }

     

       277
       277
       +
       

     

       278
       278
       +
         let transmit_and_display ?image_id ?image_number ?format ?transmission

     

       279
       279
       +
             ?compression ?width ?height ?size ?offset ?quiet ?placement () =

     

       280
       280
       +
           {

     

       281
       281
       +
             (make `Transmit_and_display) with

     

       282
       282
       +
             image_id;

     

       283
       283
       +
             image_number;

     

       284
       284
       +
             format;

     

       285
       285
       +
             transmission;

     

       286
       286
       +
             compression;

     

       287
       287
       +
             width;

     

       288
       288
       +
             height;

     

       289
       289
       +
             size;

     

       290
       290
       +
             offset;

     

       291
       291
       +
             quiet;

     

       292
       292
       +
             placement;

     

       293
       293
       +
           }

     

       294
       294
       +
       

     

       295
       295
       +
         let query ?format ?transmission ?width ?height ?quiet () =

     

       296
       296
       +
           { (make `Query) with format; transmission; width; height; quiet }

     

       297
       297
       +
       

     

       298
       298
       +
         let display ?image_id ?image_number ?placement ?quiet () =

     

       299
       299
       +
           { (make `Display) with image_id; image_number; placement; quiet }

     

       300
       300
       +
       

     

       301
       301
       +
         let delete ?quiet del = { (make `Delete) with quiet; delete = Some del }

     

       302
       302
       +
       

     

       303
       303
       +
         let frame ?image_id ?image_number ?format ?transmission ?compression ?width

     

       304
       304
       +
             ?height ?quiet ~frame () =

     

       305
       305
       +
           {

     

       306
       306
       +
             (make `Frame) with

     

       307
       307
       +
             image_id;

     

       308
       308
       +
             image_number;

     

       309
       309
       +
             format;

     

       310
       310
       +
             transmission;

     

       311
       311
       +
             compression;

     

       312
       312
       +
             width;

     

       313
       313
       +
             height;

     

       314
       314
       +
             quiet;

     

       315
       315
       +
             frame = Some frame;

     

       316
       316
       +
           }

     

       317
       317
       +
       

     

       318
       318
       +
         let animate ?image_id ?image_number ?quiet anim =

     

       319
       319
       +
           { (make `Animate) with image_id; image_number; quiet; animation = Some anim }

     

       320
       320
       +
       

     

       321
       321
       +
         let compose ?image_id ?image_number ?quiet comp =

     

       322
       322
       +
           { (make `Compose) with image_id; image_number; quiet; compose = Some comp }

     

       323
       323
       +
       

     

       324
       324
       +
         (* Serialization helpers *)

     

       325
       325
       +
         let apc_start = "\027_G"

     

       326
       326
       +
         let apc_end = "\027\\"

     

       327
       327
       +
       

     

       328
       328
       +
         (* Key-value writer with separator handling *)

     

       329
       329
       +
         type kv_writer = { mutable first : bool; buf : Buffer.t }

     

       330
       330
       +
       

     

       331
       331
       +
         let kv_writer buf = { first = true; buf }

     

       332
       332
       +
       

     

       333
       333
       +
         let kv w key value =

     

       334
       334
       +
           if not w.first then Buffer.add_char w.buf ',';

     

       335
       335
       +
           w.first <- false;

     

       336
       336
       +
           Buffer.add_char w.buf key;

     

       337
       337
       +
           Buffer.add_char w.buf '=';

     

       338
       338
       +
           Buffer.add_string w.buf value

     

       339
       339
       +
       

     

       340
       340
       +
         let kv_int w key value = kv w key (string_of_int value)

     

       341
       341
       +
         let kv_int32 w key value = kv w key (Int32.to_string value)

     

       342
       342
       +
         let kv_char w key value = kv w key (String.make 1 value)

     

       343
       343
       +
       

     

       344
       344
       +
         (* Conditional writers using Option.iter *)

     

       345
       345
       +
         let kv_int_opt w key = Option.iter (kv_int w key)

     

       346
       346
       +
         let kv_int32_opt w key = Option.iter (kv_int32 w key)

     

       347
       347
       +
       

     

       348
       348
       +
         let kv_int_if w key ~default opt =

     

       349
       349
       +
           Option.iter (fun v -> if v <> default then kv_int w key v) opt

     

       350
       350
       +
       

     

       351
       351
       +
         let action_char : action -> char = function

     

       352
       352
       +
           | `Transmit -> 't'

     

       353
       353
       +
           | `Transmit_and_display -> 'T'

     

       354
       354
       +
           | `Query -> 'q'

     

       355
       355
       +
           | `Display -> 'p'

     

       356
       356
       +
           | `Delete -> 'd'

     

       357
       357
       +
           | `Frame -> 'f'

     

       358
       358
       +
           | `Animate -> 'a'

     

       359
       359
       +
           | `Compose -> 'c'

     

       360
       360
       +
       

     

       361
       361
       +
         let delete_char : delete -> char = function

     

       362
       362
       +
           | `All_visible -> 'a'

     

       363
       363
       +
           | `All_visible_and_free -> 'A'

     

       364
       364
       +
           | `By_id _ -> 'i'

     

       365
       365
       +
           | `By_id_and_free _ -> 'I'

     

       366
       366
       +
           | `By_number _ -> 'n'

     

       367
       367
       +
           | `By_number_and_free _ -> 'N'

     

       368
       368
       +
           | `At_cursor -> 'c'

     

       369
       369
       +
           | `At_cursor_and_free -> 'C'

     

       370
       370
       +
           | `At_cell _ -> 'p'

     

       371
       371
       +
           | `At_cell_and_free _ -> 'P'

     

       372
       372
       +
           | `At_cell_z _ -> 'q'

     

       373
       373
       +
           | `At_cell_z_and_free _ -> 'Q'

     

       374
       374
       +
           | `By_column _ -> 'x'

     

       375
       375
       +
           | `By_column_and_free _ -> 'X'

     

       376
       376
       +
           | `By_row _ -> 'y'

     

       377
       377
       +
           | `By_row_and_free _ -> 'Y'

     

       378
       378
       +
           | `By_z_index _ -> 'z'

     

       379
       379
       +
           | `By_z_index_and_free _ -> 'Z'

     

       380
       380
       +
           | `By_id_range _ -> 'r'

     

       381
       381
       +
           | `By_id_range_and_free _ -> 'R'

     

       382
       382
       +
           | `Frames -> 'f'

     

       383
       383
       +
           | `Frames_and_free -> 'F'

     

       384
       384
       +
       

     

       385
       385
       +
         let write_placement w (p : Placement.t) =

     

       386
       386
       +
           kv_int_opt w 'x' p.source_x;

     

       387
       387
       +
           kv_int_opt w 'y' p.source_y;

     

       388
       388
       +
           kv_int_opt w 'w' p.source_width;

     

       389
       389
       +
           kv_int_opt w 'h' p.source_height;

     

       390
       390
       +
           kv_int_opt w 'X' p.cell_x_offset;

     

       391
       391
       +
           kv_int_opt w 'Y' p.cell_y_offset;

     

       392
       392
       +
           kv_int_opt w 'c' p.columns;

     

       393
       393
       +
           kv_int_opt w 'r' p.rows;

     

       394
       394
       +
           kv_int_opt w 'z' p.z_index;

     

       395
       395
       +
           kv_int_opt w 'p' p.placement_id;

     

       396
       396
       +
           p.cursor |> Option.iter (fun c -> kv_int_if w 'C' ~default:0 (Some (Cursor.to_int c)));

     

       397
       397
       +
           if p.unicode_placeholder then kv_int w 'U' 1

     

       398
       398
       +
       

     

       399
       399
       +
         let write_delete w (d : delete) =

     

       400
       400
       +
           kv_char w 'd' (delete_char d);

     

       401
       401
       +
           match d with

     

       402
       402
       +
           | `By_id (id, pid) | `By_id_and_free (id, pid) ->

     

       403
       403
       +
               kv_int w 'i' id;

     

       404
       404
       +
               kv_int_opt w 'p' pid

     

       405
       405
       +
           | `By_number (n, pid) | `By_number_and_free (n, pid) ->

     

       406
       406
       +
               kv_int w 'I' n;

     

       407
       407
       +
               kv_int_opt w 'p' pid

     

       408
       408
       +
           | `At_cell (x, y) | `At_cell_and_free (x, y) ->

     

       409
       409
       +
               kv_int w 'x' x;

     

       410
       410
       +
               kv_int w 'y' y

     

       411
       411
       +
           | `At_cell_z (x, y, z) | `At_cell_z_and_free (x, y, z) ->

     

       412
       412
       +
               kv_int w 'x' x;

     

       413
       413
       +
               kv_int w 'y' y;

     

       414
       414
       +
               kv_int w 'z' z

     

       415
       415
       +
           | `By_column c | `By_column_and_free c -> kv_int w 'x' c

     

       416
       416
       +
           | `By_row r | `By_row_and_free r -> kv_int w 'y' r

     

       417
       417
       +
           | `By_z_index z | `By_z_index_and_free z -> kv_int w 'z' z

     

       418
       418
       +
           | `By_id_range (min_id, max_id) | `By_id_range_and_free (min_id, max_id) ->

     

       419
       419
       +
               kv_int w 'x' min_id;

     

       420
       420
       +
               kv_int w 'y' max_id

     

       421
       421
       +
           | `All_visible | `All_visible_and_free | `At_cursor | `At_cursor_and_free

     

       422
       422
       +
           | `Frames | `Frames_and_free ->

     

       423
       423
       +
               ()

     

       424
       424
       +
       

     

       425
       425
       +
         let write_frame w (f : Frame.t) =

     

       426
       426
       +
           kv_int_opt w 'x' f.x;

     

       427
       427
       +
           kv_int_opt w 'y' f.y;

     

       428
       428
       +
           kv_int_opt w 'c' f.base_frame;

     

       429
       429
       +
           kv_int_opt w 'r' f.edit_frame;

     

       430
       430
       +
           kv_int_opt w 'z' f.gap_ms;

     

       431
       431
       +
           f.composition

     

       432
       432
       +
           |> Option.iter (fun c -> kv_int_if w 'X' ~default:0 (Some (Composition.to_int c)));

     

       433
       433
       +
           kv_int32_opt w 'Y' f.background_color

     

       434
       434
       +
       

     

       435
       435
       +
         let write_animation w : Animation.t -> unit = function

     

       436
       436
       +
           | `Set_state (state, loops) ->

     

       437
       437
       +
               let s = match state with `Stop -> 1 | `Loading -> 2 | `Run -> 3 in

     

       438
       438
       +
               kv_int w 's' s;

     

       439
       439
       +
               kv_int_opt w 'v' loops

     

       440
       440
       +
           | `Set_gap (frame, gap_ms) ->

     

       441
       441
       +
               kv_int w 'r' frame;

     

       442
       442
       +
               kv_int w 'z' gap_ms

     

       443
       443
       +
           | `Set_current frame -> kv_int w 'c' frame

     

       444
       444
       +
       

     

       445
       445
       +
         let write_compose w (c : Compose.t) =

     

       446
       446
       +
           kv_int w 'r' c.source_frame;

     

       447
       447
       +
           kv_int w 'c' c.dest_frame;

     

       448
       448
       +
           kv_int_opt w 'w' c.width;

     

       449
       449
       +
           kv_int_opt w 'h' c.height;

     

       450
       450
       +
           kv_int_opt w 'x' c.dest_x;

     

       451
       451
       +
           kv_int_opt w 'y' c.dest_y;

     

       452
       452
       +
           kv_int_opt w 'X' c.source_x;

     

       453
       453
       +
           kv_int_opt w 'Y' c.source_y;

     

       454
       454
       +
           c.composition

     

       455
       455
       +
           |> Option.iter (fun comp -> kv_int_if w 'C' ~default:0 (Some (Composition.to_int comp)))

     

       456
       456
       +
       

     

       457
       457
       +
         let write_control_data buf cmd =

     

       458
       458
       +
           let w = kv_writer buf in

     

       459
       459
       +
           (* Action *)

     

       460
       460
       +
           kv_char w 'a' (action_char cmd.action);

     

       461
       461
       +
           (* Quiet - only if non-default *)

     

       462
       462
       +
           cmd.quiet |> Option.iter (fun q -> kv_int_if w 'q' ~default:0 (Some (Quiet.to_int q)));

     

       463
       463
       +
           (* Format *)

     

       464
       464
       +
           cmd.format |> Option.iter (fun f -> kv_int w 'f' (Format.to_int f));

     

       465
       465
       +
           (* Transmission - only for transmit/frame actions, always include t=d for compatibility *)

     

       466
       466
       +
           (match cmd.action with

     

       467
       467
       +
            | `Transmit | `Transmit_and_display | `Frame ->

     

       468
       468
       +
                (match cmd.transmission with

     

       469
       469
       +
                 | Some t -> kv_char w 't' (Transmission.to_char t)

     

       470
       470
       +
                 | None -> kv_char w 't' 'd')

     

       471
       471
       +
            | _ -> ());

     

       472
       472
       +
           (* Compression *)

     

       473
       473
       +
           cmd.compression |> Option.iter (fun c -> Compression.to_char c |> Option.iter (kv_char w 'o'));

     

       474
       474
       +
           (* Dimensions *)

     

       475
       475
       +
           kv_int_opt w 's' cmd.width;

     

       476
       476
       +
           kv_int_opt w 'v' cmd.height;

     

       477
       477
       +
           (* File size/offset *)

     

       478
       478
       +
           kv_int_opt w 'S' cmd.size;

     

       479
       479
       +
           kv_int_opt w 'O' cmd.offset;

     

       480
       480
       +
           (* Image ID/number *)

     

       481
       481
       +
           kv_int_opt w 'i' cmd.image_id;

     

       482
       482
       +
           kv_int_opt w 'I' cmd.image_number;

     

       483
       483
       +
           (* Complex options *)

     

       484
       484
       +
           cmd.placement |> Option.iter (write_placement w);

     

       485
       485
       +
           cmd.delete |> Option.iter (write_delete w);

     

       486
       486
       +
           cmd.frame |> Option.iter (write_frame w);

     

       487
       487
       +
           cmd.animation |> Option.iter (write_animation w);

     

       488
       488
       +
           cmd.compose |> Option.iter (write_compose w);

     

       489
       489
       +
           w

     

       490
       490
       +
       

     

       491
       491
       +
         (* Use large chunk size to avoid chunking - Kitty animation doesn't handle chunks well *)

     

       492
       492
       +
         let chunk_size = 1024 * 1024 (* 1MB - effectively no chunking *)

     

       493
       493
       +
       

     

       494
       494
       +
         let write buf cmd ~data =

     

       495
       495
       +
           Buffer.add_string buf apc_start;

     

       496
       496
       +
           let w = write_control_data buf cmd in

     

       497
       497
       +
           if String.length data > 0 then begin

     

       498
       498
       +
             let encoded = Base64.encode_string data in

     

       499
       499
       +
             let len = String.length encoded in

     

       500
       500
       +
             if len <= chunk_size then (

     

       501
       501
       +
               Buffer.add_char buf ';';

     

       502
       502
       +
               Buffer.add_string buf encoded;

     

       503
       503
       +
               Buffer.add_string buf apc_end)

     

       504
       504
       +
             else begin

     

       505
       505
       +
               (* Multiple chunks *)

     

       506
       506
       +
               let rec write_chunks pos first =

     

       507
       507
       +
                 if pos < len then begin

     

       508
       508
       +
                   let remaining = len - pos in

     

       509
       509
       +
                   let this_chunk = min chunk_size remaining in

     

       510
       510
       +
                   let is_last = pos + this_chunk >= len in

     

       511
       511
       +
                   if first then (

     

       512
       512
       +
                     kv_int w 'm' 1;

     

       513
       513
       +
                     Buffer.add_char buf ';';

     

       514
       514
       +
                     Buffer.add_substring buf encoded pos this_chunk;

     

       515
       515
       +
                     Buffer.add_string buf apc_end)

     

       516
       516
       +
                   else (

     

       517
       517
       +
                     Buffer.add_string buf apc_start;

     

       518
       518
       +
                     Buffer.add_string buf (if is_last then "m=0" else "m=1");

     

       519
       519
       +
                     Buffer.add_char buf ';';

     

       520
       520
       +
                     Buffer.add_substring buf encoded pos this_chunk;

     

       521
       521
       +
                     Buffer.add_string buf apc_end);

     

       522
       522
       +
                   write_chunks (pos + this_chunk) false

     

       523
       523
       +
                 end

     

       524
       524
       +
               in

     

       525
       525
       +
               write_chunks 0 true

     

       526
       526
       +
             end

     

       527
       527
       +
           end

     

       528
       528
       +
           else Buffer.add_string buf apc_end

     

       529
       529
       +
       

     

       530
       530
       +
         let to_string cmd ~data =

     

       531
       531
       +
           let buf = Buffer.create 1024 in

     

       532
       532
       +
           write buf cmd ~data;

     

       533
       533
       +
           Buffer.contents buf

     

       534
       534
       +
       end

     

       535
       535
       +
       

     

       536
       536
       +
       module Response = struct

     

       537
       537
       +
         type t = {

     

       538
       538
       +
           message : string;

     

       539
       539
       +
           image_id : int option;

     

       540
       540
       +
           image_number : int option;

     

       541
       541
       +
           placement_id : int option;

     

       542
       542
       +
         }

     

       543
       543
       +
       

     

       544
       544
       +
         let is_ok t = t.message = "OK"

     

       545
       545
       +
         let message t = t.message

     

       546
       546
       +
       

     

       547
       547
       +
         let error_code t =

     

       548
       548
       +
           if is_ok t then None

     

       549
       549
       +
           else String.index_opt t.message ':' |> Option.fold ~none:(Some t.message) ~some:(fun i -> Some (String.sub t.message 0 i))

     

       550
       550
       +
       

     

       551
       551
       +
         let image_id t = t.image_id

     

       552
       552
       +
         let image_number t = t.image_number

     

       553
       553
       +
         let placement_id t = t.placement_id

     

       554
       554
       +
       

     

       555
       555
       +
         let parse s =

     

       556
       556
       +
           let ( let* ) = Option.bind in

     

       557
       557
       +
           let esc = '\027' in

     

       558
       558
       +
           let len = String.length s in

     

       559
       559
       +
           let* () = if len >= 5 && s.[0] = esc && s.[1] = '_' && s.[2] = 'G' then Some () else None in

     

       560
       560
       +
           let* semi_pos = String.index_from_opt s 3 ';' in

     

       561
       561
       +
           let rec find_end pos =

     

       562
       562
       +
             if pos + 1 < len && s.[pos] = esc && s.[pos + 1] = '\\' then Some pos

     

       563
       563
       +
             else if pos + 1 < len then find_end (pos + 1)

     

       564
       564
       +
             else None

     

       565
       565
       +
           in

     

       566
       566
       +
           let* end_pos = find_end (semi_pos + 1) in

     

       567
       567
       +
           let keys_str = String.sub s 3 (semi_pos - 3) in

     

       568
       568
       +
           let message = String.sub s (semi_pos + 1) (end_pos - semi_pos - 1) in

     

       569
       569
       +
           let parse_kv part =

     

       570
       570
       +
             if String.length part >= 3 && part.[1] = '=' then

     

       571
       571
       +
               Some (part.[0], String.sub part 2 (String.length part - 2))

     

       572
       572
       +
             else None

     

       573
       573
       +
           in

     

       574
       574
       +
           let keys = String.split_on_char ',' keys_str |> List.filter_map parse_kv in

     

       575
       575
       +
           let find_int key = List.assoc_opt key keys |> Fun.flip Option.bind int_of_string_opt in

     

       576
       576
       +
           Some

     

       577
       577
       +
             {

     

       578
       578
       +
               message;

     

       579
       579
       +
               image_id = find_int 'i';

     

       580
       580
       +
               image_number = find_int 'I';

     

       581
       581
       +
               placement_id = find_int 'p';

     

       582
       582
       +
             }

     

       583
       583
       +
       end

     

       584
       584
       +
       

     

       585
       585
       +
       module Unicode_placeholder = struct

     

       586
       586
       +
         let placeholder_char = Uchar.of_int 0x10EEEE

     

       587
       587
       +
       

     

       588
       588
       +
         let diacritics =

     

       589
       589
       +
           [|

     

       590
       590
       +
             0x0305; 0x030D; 0x030E; 0x0310; 0x0312; 0x033D; 0x033E; 0x033F;

     

       591
       591
       +
             0x0346; 0x034A; 0x034B; 0x034C; 0x0350; 0x0351; 0x0352; 0x0357;

     

       592
       592
       +
             0x035B; 0x0363; 0x0364; 0x0365; 0x0366; 0x0367; 0x0368; 0x0369;

     

       593
       593
       +
             0x036A; 0x036B; 0x036C; 0x036D; 0x036E; 0x036F; 0x0483; 0x0484;

     

       594
       594
       +
             0x0485; 0x0486; 0x0487; 0x0592; 0x0593; 0x0594; 0x0595; 0x0597;

     

       595
       595
       +
             0x0598; 0x0599; 0x059C; 0x059D; 0x059E; 0x059F; 0x05A0; 0x05A1;

     

       596
       596
       +
             0x05A8; 0x05A9; 0x05AB; 0x05AC; 0x05AF; 0x05C4; 0x0610; 0x0611;

     

       597
       597
       +
             0x0612; 0x0613; 0x0614; 0x0615; 0x0616; 0x0617; 0x0657; 0x0658;

     

       598
       598
       +
             0x0659; 0x065A; 0x065B; 0x065D; 0x065E; 0x06D6; 0x06D7; 0x06D8;

     

       599
       599
       +
             0x06D9; 0x06DA; 0x06DB; 0x06DC; 0x06DF; 0x06E0; 0x06E1; 0x06E2;

     

       600
       600
       +
             0x06E4; 0x06E7; 0x06E8; 0x06EB; 0x06EC; 0x0730; 0x0732; 0x0733;

     

       601
       601
       +
             0x0735; 0x0736; 0x073A; 0x073D; 0x073F; 0x0740; 0x0741; 0x0743;

     

       602
       602
       +
             0x0745; 0x0747; 0x0749; 0x074A; 0x07EB; 0x07EC; 0x07ED; 0x07EE;

     

       603
       603
       +
             0x07EF; 0x07F0; 0x07F1; 0x07F3; 0x0816; 0x0817; 0x0818; 0x0819;

     

       604
       604
       +
             0x081B; 0x081C; 0x081D; 0x081E; 0x081F; 0x0820; 0x0821; 0x0822;

     

       605
       605
       +
             0x0823; 0x0825; 0x0826; 0x0827; 0x0829; 0x082A; 0x082B; 0x082C;

     

       606
       606
       +
             0x082D; 0x0951; 0x0953; 0x0954; 0x0F82; 0x0F83; 0x0F86; 0x0F87;

     

       607
       607
       +
             0x135D; 0x135E; 0x135F; 0x17DD; 0x193A; 0x1A17; 0x1A75; 0x1A76;

     

       608
       608
       +
             0x1A77; 0x1A78; 0x1A79; 0x1A7A; 0x1A7B; 0x1A7C; 0x1B6B; 0x1B6D;

     

       609
       609
       +
             0x1B6E; 0x1B6F; 0x1B70; 0x1B71; 0x1B72; 0x1B73; 0x1CD0; 0x1CD1;

     

       610
       610
       +
             0x1CD2; 0x1CDA; 0x1CDB; 0x1CE0; 0x1DC0; 0x1DC1; 0x1DC3; 0x1DC4;

     

       611
       611
       +
             0x1DC5; 0x1DC6; 0x1DC7; 0x1DC8; 0x1DC9; 0x1DCB; 0x1DCC; 0x1DD1;

     

       612
       612
       +
             0x1DD2; 0x1DD3; 0x1DD4; 0x1DD5; 0x1DD6; 0x1DD7; 0x1DD8; 0x1DD9;

     

       613
       613
       +
             0x1DDA; 0x1DDB; 0x1DDC; 0x1DDD; 0x1DDE; 0x1DDF; 0x1DE0; 0x1DE1;

     

       614
       614
       +
             0x1DE2; 0x1DE3; 0x1DE4; 0x1DE5; 0x1DE6; 0x1DFE; 0x20D0; 0x20D1;

     

       615
       615
       +
             0x20D4; 0x20D5; 0x20D6; 0x20D7; 0x20DB; 0x20DC; 0x20E1; 0x20E7;

     

       616
       616
       +
             0x20E9; 0x20F0; 0xA66F; 0xA67C; 0xA67D; 0xA6F0; 0xA6F1; 0xA8E0;

     

       617
       617
       +
             0xA8E1; 0xA8E2; 0xA8E3; 0xA8E4; 0xA8E5; 0xA8E6; 0xA8E7; 0xA8E8;

     

       618
       618
       +
             0xA8E9; 0xA8EA; 0xA8EB; 0xA8EC; 0xA8ED; 0xA8EE; 0xA8EF; 0xA8F0;

     

       619
       619
       +
             0xA8F1; 0xAAB0; 0xAAB2; 0xAAB3; 0xAAB7; 0xAAB8; 0xAABE; 0xAABF;

     

       620
       620
       +
             0xAAC1; 0xFE20; 0xFE21; 0xFE22; 0xFE23; 0xFE24; 0xFE25; 0xFE26;

     

       621
       621
       +
             0x10A0F; 0x10A38; 0x1D185; 0x1D186; 0x1D187; 0x1D188; 0x1D189;

     

       622
       622
       +
             0x1D1AA; 0x1D1AB; 0x1D1AC; 0x1D1AD; 0x1D242; 0x1D243; 0x1D244;

     

       623
       623
       +
           |]

     

       624
       624
       +
       

     

       625
       625
       +
         let diacritic n =

     

       626
       626
       +
           Uchar.of_int diacritics.(n mod Array.length diacritics)

     

       627
       627
       +
       

     

       628
       628
       +
         let row_diacritic = diacritic

     

       629
       629
       +
         let column_diacritic = diacritic

     

       630
       630
       +
         let id_high_byte_diacritic = diacritic

     

       631
       631
       +
       

     

       632
       632
       +
         let add_uchar buf u =

     

       633
       633
       +
           let code = Uchar.to_int u in

     

       634
       634
       +
           let put = Buffer.add_char buf in

     

       635
       635
       +
           if code < 0x80 then put (Char.chr code)

     

       636
       636
       +
           else if code < 0x800 then (

     

       637
       637
       +
             put (Char.chr (0xC0 lor (code lsr 6)));

     

       638
       638
       +
             put (Char.chr (0x80 lor (code land 0x3F))))

     

       639
       639
       +
           else if code < 0x10000 then (

     

       640
       640
       +
             put (Char.chr (0xE0 lor (code lsr 12)));

     

       641
       641
       +
             put (Char.chr (0x80 lor ((code lsr 6) land 0x3F)));

     

       642
       642
       +
             put (Char.chr (0x80 lor (code land 0x3F))))

     

       643
       643
       +
           else (

     

       644
       644
       +
             put (Char.chr (0xF0 lor (code lsr 18)));

     

       645
       645
       +
             put (Char.chr (0x80 lor ((code lsr 12) land 0x3F)));

     

       646
       646
       +
             put (Char.chr (0x80 lor ((code lsr 6) land 0x3F)));

     

       647
       647
       +
             put (Char.chr (0x80 lor (code land 0x3F))))

     

       648
       648
       +
       

     

       649
       649
       +
         let write buf ~image_id ?placement_id ~rows ~cols () =

     

       650
       650
       +
           (* Set foreground color *)

     

       651
       651
       +
           Printf.bprintf buf "\027[38;2;%d;%d;%dm"

     

       652
       652
       +
             ((image_id lsr 16) land 0xFF)

     

       653
       653
       +
             ((image_id lsr 8) land 0xFF)

     

       654
       654
       +
             (image_id land 0xFF);

     

       655
       655
       +
           (* Optional placement ID in underline color *)

     

       656
       656
       +
           placement_id

     

       657
       657
       +
           |> Option.iter (fun pid ->

     

       658
       658
       +
                  Printf.bprintf buf "\027[58;2;%d;%d;%dm"

     

       659
       659
       +
                    ((pid lsr 16) land 0xFF)

     

       660
       660
       +
                    ((pid lsr 8) land 0xFF)

     

       661
       661
       +
                    (pid land 0xFF));

     

       662
       662
       +
           (* High byte diacritic *)

     

       663
       663
       +
           let high_byte = (image_id lsr 24) land 0xFF in

     

       664
       664
       +
           let high_diac = if high_byte > 0 then Some (id_high_byte_diacritic high_byte) else None in

     

       665
       665
       +
           (* Write grid *)

     

       666
       666
       +
           for row = 0 to rows - 1 do

     

       667
       667
       +
             for col = 0 to cols - 1 do

     

       668
       668
       +
               add_uchar buf placeholder_char;

     

       669
       669
       +
               add_uchar buf (row_diacritic row);

     

       670
       670
       +
               add_uchar buf (column_diacritic col);

     

       671
       671
       +
               high_diac |> Option.iter (add_uchar buf)

     

       672
       672
       +
             done;

     

       673
       673
       +
             if row < rows - 1 then Buffer.add_string buf "\n\r"

     

       674
       674
       +
           done;

     

       675
       675
       +
           (* Reset colors *)

     

       676
       676
       +
           Buffer.add_string buf "\027[39m";

     

       677
       677
       +
           if Option.is_some placement_id then Buffer.add_string buf "\027[59m"

     

       678
       678
       +
       end

     

       679
       679
       +
       

     

       680
       680
       +
       module Detect = struct

     

       681
       681
       +
         let make_query () =

     

       682
       682
       +
           let cmd = Command.query ~format:`Rgb24 ~transmission:`Direct ~width:1 ~height:1 () in

     

       683
       683
       +
           Command.to_string cmd ~data:"\x00\x00\x00"

     

       684
       684
       +
       

     

       685
       685
       +
         let supports_graphics response ~da1_received =

     

       686
       686
       +
           response |> Option.map Response.is_ok |> Option.value ~default:(not da1_received)

     

       687
       687
       +
       end

+402

lib/kitty_graphics.mli

···

       1
       1
       +
       (** Kitty Terminal Graphics Protocol

     

       2
       2
       +
       

     

       3
       3
       +
           This library implements the Kitty terminal graphics protocol, allowing

     

       4
       4
       +
           OCaml programs to display images in terminals that support the protocol

     

       5
       5
       +
           (Kitty, WezTerm, Konsole, Ghostty, etc.).

     

       6
       6
       +
       

     

       7
       7
       +
           The protocol uses APC (Application Programming Command) escape sequences

     

       8
       8
       +
           to transmit and display pixel graphics. Images can be transmitted as raw

     

       9
       9
       +
           RGB/RGBA data or PNG, and displayed at specific positions with various

     

       10
       10
       +
           placement options.

     

       11
       11
       +
       

     

       12
       12
       +
           {2 Basic Usage}

     

       13
       13
       +
       

     

       14
       14
       +
           {[

     

       15
       15
       +
             (* Display a PNG image *)

     

       16
       16
       +
             let png_data = read_file "image.png" in

     

       17
       17
       +
             let cmd = Kitty_graphics.Command.transmit_and_display ~format:`Png () in

     

       18
       18
       +
             let buf = Buffer.create 1024 in

     

       19
       19
       +
             Kitty_graphics.Command.write buf cmd ~data:png_data;

     

       20
       20
       +
             print_string (Buffer.contents buf)

     

       21
       21
       +
           ]}

     

       22
       22
       +
       

     

       23
       23
       +
           {2 Protocol Reference}

     

       24
       24
       +
       

     

       25
       25
       +
           See {{:https://sw.kovidgoyal.net/kitty/graphics-protocol/} Kitty Graphics Protocol}

     

       26
       26
       +
           for the full specification. *)

     

       27
       27
       +
       

     

       28
       28
       +
       (** {1 Polymorphic Variant Types} *)

     

       29
       29
       +
       

     

       30
       30
       +
       type format = [ `Rgba32 | `Rgb24 | `Png ]

     

       31
       31
       +
       (** Image data formats. [`Rgba32] is 32-bit RGBA (4 bytes per pixel),

     

       32
       32
       +
           [`Rgb24] is 24-bit RGB (3 bytes per pixel), [`Png] is PNG encoded data. *)

     

       33
       33
       +
       

     

       34
       34
       +
       type transmission = [ `Direct | `File | `Tempfile ]

     

       35
       35
       +
       (** Transmission methods. [`Direct] sends data inline, [`File] reads from a path,

     

       36
       36
       +
           [`Tempfile] reads from a temp file that the terminal deletes after reading. *)

     

       37
       37
       +
       

     

       38
       38
       +
       type compression = [ `None | `Zlib ]

     

       39
       39
       +
       (** Compression options. [`None] for raw data, [`Zlib] for RFC 1950 compression. *)

     

       40
       40
       +
       

     

       41
       41
       +
       type quiet = [ `Noisy | `Errors_only | `Silent ]

     

       42
       42
       +
       (** Response suppression. [`Noisy] sends all responses (default),

     

       43
       43
       +
           [`Errors_only] suppresses OK responses, [`Silent] suppresses all. *)

     

       44
       44
       +
       

     

       45
       45
       +
       type cursor = [ `Move | `Static ]

     

       46
       46
       +
       (** Cursor movement after displaying. [`Move] advances cursor (default),

     

       47
       47
       +
           [`Static] keeps cursor in place. *)

     

       48
       48
       +
       

     

       49
       49
       +
       type composition = [ `Alpha_blend | `Overwrite ]

     

       50
       50
       +
       (** Composition modes. [`Alpha_blend] for full blending (default),

     

       51
       51
       +
           [`Overwrite] for simple pixel replacement. *)

     

       52
       52
       +
       

     

       53
       53
       +
       type delete =

     

       54
       54
       +
         [ `All_visible

     

       55
       55
       +
         | `All_visible_and_free

     

       56
       56
       +
         | `By_id of int * int option

     

       57
       57
       +
         | `By_id_and_free of int * int option

     

       58
       58
       +
         | `By_number of int * int option

     

       59
       59
       +
         | `By_number_and_free of int * int option

     

       60
       60
       +
         | `At_cursor

     

       61
       61
       +
         | `At_cursor_and_free

     

       62
       62
       +
         | `At_cell of int * int

     

       63
       63
       +
         | `At_cell_and_free of int * int

     

       64
       64
       +
         | `At_cell_z of int * int * int

     

       65
       65
       +
         | `At_cell_z_and_free of int * int * int

     

       66
       66
       +
         | `By_column of int

     

       67
       67
       +
         | `By_column_and_free of int

     

       68
       68
       +
         | `By_row of int

     

       69
       69
       +
         | `By_row_and_free of int

     

       70
       70
       +
         | `By_z_index of int

     

       71
       71
       +
         | `By_z_index_and_free of int

     

       72
       72
       +
         | `By_id_range of int * int

     

       73
       73
       +
         | `By_id_range_and_free of int * int

     

       74
       74
       +
         | `Frames

     

       75
       75
       +
         | `Frames_and_free ]

     

       76
       76
       +
       (** Delete target specification. Each variant has two forms: one that only

     

       77
       77
       +
           removes placements (e.g., [`All_visible]) and one that also frees the

     

       78
       78
       +
           image data (e.g., [`All_visible_and_free]). Tuple variants contain

     

       79
       79
       +
           (image_id, optional_placement_id) or (x, y) coordinates. *)

     

       80
       80
       +
       

     

       81
       81
       +
       type animation_state = [ `Stop | `Loading | `Run ]

     

       82
       82
       +
       (** Animation playback state. [`Stop] halts animation, [`Loading] runs but

     

       83
       83
       +
           waits for new frames at end, [`Run] runs normally and loops. *)

     

       84
       84
       +
       

     

       85
       85
       +
       (** {1 Type Modules} *)

     

       86
       86
       +
       

     

       87
       87
       +
       module Format : sig

     

       88
       88
       +
         type t = format

     

       89
       89
       +
       

     

       90
       90
       +
         val to_int : t -> int

     

       91
       91
       +
         (** Convert to protocol integer value (32, 24, or 100). *)

     

       92
       92
       +
       end

     

       93
       93
       +
       

     

       94
       94
       +
       module Transmission : sig

     

       95
       95
       +
         type t = transmission

     

       96
       96
       +
       

     

       97
       97
       +
         val to_char : t -> char

     

       98
       98
       +
         (** Convert to protocol character ('d', 'f', or 't'). *)

     

       99
       99
       +
       end

     

       100
       100
       +
       

     

       101
       101
       +
       module Compression : sig

     

       102
       102
       +
         type t = compression

     

       103
       103
       +
       

     

       104
       104
       +
         val to_char : t -> char option

     

       105
       105
       +
         (** Convert to protocol character ([None] or [Some 'z']). *)

     

       106
       106
       +
       end

     

       107
       107
       +
       

     

       108
       108
       +
       module Quiet : sig

     

       109
       109
       +
         type t = quiet

     

       110
       110
       +
       

     

       111
       111
       +
         val to_int : t -> int

     

       112
       112
       +
         (** Convert to protocol integer (0, 1, or 2). *)

     

       113
       113
       +
       end

     

       114
       114
       +
       

     

       115
       115
       +
       module Cursor : sig

     

       116
       116
       +
         type t = cursor

     

       117
       117
       +
       

     

       118
       118
       +
         val to_int : t -> int

     

       119
       119
       +
         (** Convert to protocol integer (0 or 1). *)

     

       120
       120
       +
       end

     

       121
       121
       +
       

     

       122
       122
       +
       module Composition : sig

     

       123
       123
       +
         type t = composition

     

       124
       124
       +
       

     

       125
       125
       +
         val to_int : t -> int

     

       126
       126
       +
         (** Convert to protocol integer (0 or 1). *)

     

       127
       127
       +
       end

     

       128
       128
       +
       

     

       129
       129
       +
       module Delete : sig

     

       130
       130
       +
         type t = delete

     

       131
       131
       +
       end

     

       132
       132
       +
       

     

       133
       133
       +
       (** {1 Placement Options} *)

     

       134
       134
       +
       

     

       135
       135
       +
       module Placement : sig

     

       136
       136
       +
         type t

     

       137
       137
       +
         (** Placement configuration. *)

     

       138
       138
       +
       

     

       139
       139
       +
         val make :

     

       140
       140
       +
           ?source_x:int ->

     

       141
       141
       +
           ?source_y:int ->

     

       142
       142
       +
           ?source_width:int ->

     

       143
       143
       +
           ?source_height:int ->

     

       144
       144
       +
           ?cell_x_offset:int ->

     

       145
       145
       +
           ?cell_y_offset:int ->

     

       146
       146
       +
           ?columns:int ->

     

       147
       147
       +
           ?rows:int ->

     

       148
       148
       +
           ?z_index:int ->

     

       149
       149
       +
           ?placement_id:int ->

     

       150
       150
       +
           ?cursor:cursor ->

     

       151
       151
       +
           ?unicode_placeholder:bool ->

     

       152
       152
       +
           unit ->

     

       153
       153
       +
           t

     

       154
       154
       +
         (** Create a placement configuration.

     

       155
       155
       +
       

     

       156
       156
       +
             @param source_x Left edge of source rectangle in pixels (default 0)

     

       157
       157
       +
             @param source_y Top edge of source rectangle in pixels (default 0)

     

       158
       158
       +
             @param source_width Width of source rectangle (default: full width)

     

       159
       159
       +
             @param source_height Height of source rectangle (default: full height)

     

       160
       160
       +
             @param cell_x_offset X offset within the first cell in pixels

     

       161
       161
       +
             @param cell_y_offset Y offset within the first cell in pixels

     

       162
       162
       +
             @param columns Number of columns to display over (scales image)

     

       163
       163
       +
             @param rows Number of rows to display over (scales image)

     

       164
       164
       +
             @param z_index Stacking order (negative = under text)

     

       165
       165
       +
             @param placement_id Unique ID for this placement

     

       166
       166
       +
             @param cursor Cursor movement policy after display

     

       167
       167
       +
             @param unicode_placeholder Create virtual placement for Unicode mode *)

     

       168
       168
       +
       

     

       169
       169
       +
         val empty : t

     

       170
       170
       +
         (** Empty placement with all defaults. *)

     

       171
       171
       +
       end

     

       172
       172
       +
       

     

       173
       173
       +
       (** {1 Animation} *)

     

       174
       174
       +
       

     

       175
       175
       +
       module Frame : sig

     

       176
       176
       +
         type t

     

       177
       177
       +
         (** Animation frame configuration. *)

     

       178
       178
       +
       

     

       179
       179
       +
         val make :

     

       180
       180
       +
           ?x:int ->

     

       181
       181
       +
           ?y:int ->

     

       182
       182
       +
           ?base_frame:int ->

     

       183
       183
       +
           ?edit_frame:int ->

     

       184
       184
       +
           ?gap_ms:int ->

     

       185
       185
       +
           ?composition:composition ->

     

       186
       186
       +
           ?background_color:int32 ->

     

       187
       187
       +
           unit ->

     

       188
       188
       +
           t

     

       189
       189
       +
         (** Create a frame specification.

     

       190
       190
       +
       

     

       191
       191
       +
             @param x Left edge where frame data is placed (pixels)

     

       192
       192
       +
             @param y Top edge where frame data is placed (pixels)

     

       193
       193
       +
             @param base_frame 1-based frame number to use as background canvas

     

       194
       194
       +
             @param edit_frame 1-based frame number to edit (0 = new frame)

     

       195
       195
       +
             @param gap_ms Delay before next frame in milliseconds

     

       196
       196
       +
             @param composition How to blend pixels onto the canvas

     

       197
       197
       +
             @param background_color 32-bit RGBA background when no base frame *)

     

       198
       198
       +
       

     

       199
       199
       +
         val empty : t

     

       200
       200
       +
         (** Empty frame spec with defaults. *)

     

       201
       201
       +
       end

     

       202
       202
       +
       

     

       203
       203
       +
       module Animation : sig

     

       204
       204
       +
         type state = animation_state

     

       205
       205
       +
       

     

       206
       206
       +
         type t =

     

       207
       207
       +
           [ `Set_state of state * int option

     

       208
       208
       +
           | `Set_gap of int * int

     

       209
       209
       +
           | `Set_current of int ]

     

       210
       210
       +
         (** Animation control operations. *)

     

       211
       211
       +
       

     

       212
       212
       +
         val set_state : ?loops:int -> state -> t

     

       213
       213
       +
         (** Set animation state.

     

       214
       214
       +
             @param loops Number of loops: 0 = ignored, 1 = infinite, n = n-1 loops *)

     

       215
       215
       +
       

     

       216
       216
       +
         val set_gap : frame:int -> gap_ms:int -> t

     

       217
       217
       +
         (** Set the gap (delay) for a specific frame.

     

       218
       218
       +
             @param frame 1-based frame number

     

       219
       219
       +
             @param gap_ms Delay in milliseconds (negative = gapless) *)

     

       220
       220
       +
       

     

       221
       221
       +
         val set_current_frame : int -> t

     

       222
       222
       +
         (** Make a specific frame (1-based) the current displayed frame. *)

     

       223
       223
       +
       end

     

       224
       224
       +
       

     

       225
       225
       +
       module Compose : sig

     

       226
       226
       +
         type t

     

       227
       227
       +
         (** Composition operation. *)

     

       228
       228
       +
       

     

       229
       229
       +
         val make :

     

       230
       230
       +
           source_frame:int ->

     

       231
       231
       +
           dest_frame:int ->

     

       232
       232
       +
           ?width:int ->

     

       233
       233
       +
           ?height:int ->

     

       234
       234
       +
           ?source_x:int ->

     

       235
       235
       +
           ?source_y:int ->

     

       236
       236
       +
           ?dest_x:int ->

     

       237
       237
       +
           ?dest_y:int ->

     

       238
       238
       +
           ?composition:composition ->

     

       239
       239
       +
           unit ->

     

       240
       240
       +
           t

     

       241
       241
       +
         (** Compose a rectangle from one frame onto another. *)

     

       242
       242
       +
       end

     

       243
       243
       +
       

     

       244
       244
       +
       (** {1 Commands} *)

     

       245
       245
       +
       

     

       246
       246
       +
       module Command : sig

     

       247
       247
       +
         type t

     

       248
       248
       +
         (** A graphics protocol command. *)

     

       249
       249
       +
       

     

       250
       250
       +
         (** {2 Image Transmission} *)

     

       251
       251
       +
       

     

       252
       252
       +
         val transmit :

     

       253
       253
       +
           ?image_id:int ->

     

       254
       254
       +
           ?image_number:int ->

     

       255
       255
       +
           ?format:format ->

     

       256
       256
       +
           ?transmission:transmission ->

     

       257
       257
       +
           ?compression:compression ->

     

       258
       258
       +
           ?width:int ->

     

       259
       259
       +
           ?height:int ->

     

       260
       260
       +
           ?size:int ->

     

       261
       261
       +
           ?offset:int ->

     

       262
       262
       +
           ?quiet:quiet ->

     

       263
       263
       +
           unit ->

     

       264
       264
       +
           t

     

       265
       265
       +
         (** Transmit image data without displaying. *)

     

       266
       266
       +
       

     

       267
       267
       +
         val transmit_and_display :

     

       268
       268
       +
           ?image_id:int ->

     

       269
       269
       +
           ?image_number:int ->

     

       270
       270
       +
           ?format:format ->

     

       271
       271
       +
           ?transmission:transmission ->

     

       272
       272
       +
           ?compression:compression ->

     

       273
       273
       +
           ?width:int ->

     

       274
       274
       +
           ?height:int ->

     

       275
       275
       +
           ?size:int ->

     

       276
       276
       +
           ?offset:int ->

     

       277
       277
       +
           ?quiet:quiet ->

     

       278
       278
       +
           ?placement:Placement.t ->

     

       279
       279
       +
           unit ->

     

       280
       280
       +
           t

     

       281
       281
       +
         (** Transmit image data and display it immediately. *)

     

       282
       282
       +
       

     

       283
       283
       +
         val query :

     

       284
       284
       +
           ?format:format ->

     

       285
       285
       +
           ?transmission:transmission ->

     

       286
       286
       +
           ?width:int ->

     

       287
       287
       +
           ?height:int ->

     

       288
       288
       +
           ?quiet:quiet ->

     

       289
       289
       +
           unit ->

     

       290
       290
       +
           t

     

       291
       291
       +
         (** Query terminal support without storing the image. *)

     

       292
       292
       +
       

     

       293
       293
       +
         (** {2 Display} *)

     

       294
       294
       +
       

     

       295
       295
       +
         val display :

     

       296
       296
       +
           ?image_id:int ->

     

       297
       297
       +
           ?image_number:int ->

     

       298
       298
       +
           ?placement:Placement.t ->

     

       299
       299
       +
           ?quiet:quiet ->

     

       300
       300
       +
           unit ->

     

       301
       301
       +
           t

     

       302
       302
       +
         (** Display a previously transmitted image. *)

     

       303
       303
       +
       

     

       304
       304
       +
         (** {2 Deletion} *)

     

       305
       305
       +
       

     

       306
       306
       +
         val delete : ?quiet:quiet -> delete -> t

     

       307
       307
       +
         (** Delete images or placements. *)

     

       308
       308
       +
       

     

       309
       309
       +
         (** {2 Animation} *)

     

       310
       310
       +
       

     

       311
       311
       +
         val frame :

     

       312
       312
       +
           ?image_id:int ->

     

       313
       313
       +
           ?image_number:int ->

     

       314
       314
       +
           ?format:format ->

     

       315
       315
       +
           ?transmission:transmission ->

     

       316
       316
       +
           ?compression:compression ->

     

       317
       317
       +
           ?width:int ->

     

       318
       318
       +
           ?height:int ->

     

       319
       319
       +
           ?quiet:quiet ->

     

       320
       320
       +
           frame:Frame.t ->

     

       321
       321
       +
           unit ->

     

       322
       322
       +
           t

     

       323
       323
       +
         (** Transmit animation frame data. *)

     

       324
       324
       +
       

     

       325
       325
       +
         val animate : ?image_id:int -> ?image_number:int -> ?quiet:quiet -> Animation.t -> t

     

       326
       326
       +
         (** Control animation playback. *)

     

       327
       327
       +
       

     

       328
       328
       +
         val compose : ?image_id:int -> ?image_number:int -> ?quiet:quiet -> Compose.t -> t

     

       329
       329
       +
         (** Compose animation frames. *)

     

       330
       330
       +
       

     

       331
       331
       +
         (** {2 Output} *)

     

       332
       332
       +
       

     

       333
       333
       +
         val write : Buffer.t -> t -> data:string -> unit

     

       334
       334
       +
         (** Write the command to a buffer. *)

     

       335
       335
       +
       

     

       336
       336
       +
         val to_string : t -> data:string -> string

     

       337
       337
       +
         (** Convert command to a string. *)

     

       338
       338
       +
       end

     

       339
       339
       +
       

     

       340
       340
       +
       (** {1 Response Parsing} *)

     

       341
       341
       +
       

     

       342
       342
       +
       module Response : sig

     

       343
       343
       +
         type t

     

       344
       344
       +
         (** A parsed terminal response. *)

     

       345
       345
       +
       

     

       346
       346
       +
         val parse : string -> t option

     

       347
       347
       +
         (** Parse a response from terminal output. *)

     

       348
       348
       +
       

     

       349
       349
       +
         val is_ok : t -> bool

     

       350
       350
       +
         (** Check if the response indicates success. *)

     

       351
       351
       +
       

     

       352
       352
       +
         val message : t -> string

     

       353
       353
       +
         (** Get the response message. *)

     

       354
       354
       +
       

     

       355
       355
       +
         val error_code : t -> string option

     

       356
       356
       +
         (** Extract the error code if this is an error response. *)

     

       357
       357
       +
       

     

       358
       358
       +
         val image_id : t -> int option

     

       359
       359
       +
         (** Get the image ID from the response. *)

     

       360
       360
       +
       

     

       361
       361
       +
         val image_number : t -> int option

     

       362
       362
       +
         (** Get the image number from the response. *)

     

       363
       363
       +
       

     

       364
       364
       +
         val placement_id : t -> int option

     

       365
       365
       +
         (** Get the placement ID from the response. *)

     

       366
       366
       +
       end

     

       367
       367
       +
       

     

       368
       368
       +
       (** {1 Unicode Placeholders} *)

     

       369
       369
       +
       

     

       370
       370
       +
       module Unicode_placeholder : sig

     

       371
       371
       +
         val placeholder_char : Uchar.t

     

       372
       372
       +
         (** The Unicode placeholder character U+10EEEE. *)

     

       373
       373
       +
       

     

       374
       374
       +
         val write :

     

       375
       375
       +
           Buffer.t ->

     

       376
       376
       +
           image_id:int ->

     

       377
       377
       +
           ?placement_id:int ->

     

       378
       378
       +
           rows:int ->

     

       379
       379
       +
           cols:int ->

     

       380
       380
       +
           unit ->

     

       381
       381
       +
           unit

     

       382
       382
       +
         (** Write placeholder characters to a buffer. *)

     

       383
       383
       +
       

     

       384
       384
       +
         val row_diacritic : int -> Uchar.t

     

       385
       385
       +
         (** Get the combining diacritic for a row number (0-based). *)

     

       386
       386
       +
       

     

       387
       387
       +
         val column_diacritic : int -> Uchar.t

     

       388
       388
       +
         (** Get the combining diacritic for a column number (0-based). *)

     

       389
       389
       +
       

     

       390
       390
       +
         val id_high_byte_diacritic : int -> Uchar.t

     

       391
       391
       +
         (** Get the diacritic for the high byte of a 32-bit image ID. *)

     

       392
       392
       +
       end

     

       393
       393
       +
       

     

       394
       394
       +
       (** {1 Terminal Detection} *)

     

       395
       395
       +
       

     

       396
       396
       +
       module Detect : sig

     

       397
       397
       +
         val make_query : unit -> string

     

       398
       398
       +
         (** Generate a query command to test graphics support. *)

     

       399
       399
       +
       

     

       400
       400
       +
         val supports_graphics : Response.t option -> da1_received:bool -> bool

     

       401
       401
       +
         (** Determine if graphics are supported based on query results. *)

     

       402
       402
       +
       end