mirrors/kitty
1
0
Fork 0
mirror of https://github.com/kovidgoyal/kitty synced 2026-07-27 18:51:41 +02:00
Code Issues Packages Projects Releases Wiki Activity

Document the image display protocol

Browse Source
This commit is contained in:
Kovid Goyal
2017-10-05 18:08:12 +05:30
parent 49aeae4aad
commit 57a6d53a45
1 changed files with 49 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
graphics-protocol.asciidoc
View File

@@ -199,15 +199,51 @@ printable characters and spaces. The string will be `OK` if reading the pixel
data succeeded or an error message. data succeeded or an error message.
== Display images on screen
Every transmitted image can be displayed an arbitrary number of times on the
screen, in different locations, using different parts of the source image, as
needed. You can either simultaneously transmit and display an image using the
action `a=T`, or first transmit the image with a id, such as `i=10` and then display
it with `a=p,i=10` which will display the previously transmitted image at the current
cursor position.
=== Controlling displayed image layout
The image is rendered at the current cursor position, from the upper left corner of
the current cell. You can also specify extra `X=3` and `Y=4` pixel offsets to display from
a different origin within the cell. Note that the offsets must be smaller that the size of the cell.
By default, the entire image will be displayed (images wider than the available
width will be truncated on the right edge). You can choose a source rectangle (in pixels)
as the part of the image to display. This is done with the keys: `x, y, w, h` which specify
the top-left corner, width and height of the source rectangle.
You can also ask the terminal emulator to display the image in a specified rectangle
(num of columns / num of lines), using the control codes `c,r`. `c` is the number of columns
and `r` the number of rows. The image will be scaled (enlarged/shrunk) as needed to fit
the specified area. Note that if you specify a start cell offset via the `X,Y` keys, it is not
added to the number of rows/columns.
Finally, you can specify the image *z-index*, i.e. the vertical stacking order. Images
placed in the same location with different z-index values will be blended if
they are semi-transparent. You can specify z-index values using the `z` key.
Negative z-index values mean that the images will be drawn under the text. This
allows rendering of text on top of images.
== Control data reference == Control data reference
The table below shows all the control data keys as well as what values they can The table below shows all the control data keys as well as what values they can
take, and the default value they take when missing. take, and the default value they take when missing.
[cols="^1,<3,^1,<6"]
|=== |===
|Key | Value | Default | Description |Key | Value | Default | Description
| `a` | Single character. `(t, T, q, p)` | `t` | The overall action this graphics command is performing. | `a` | Single character. `(t, T, p)` | `t` | The overall action this graphics command is performing.
4+^h| Keys for image transmission
| `f` | Positive integer. `(24, 32, 100)`. | `32` | The format in which the image data is sent. | `f` | Positive integer. `(24, 32, 100)`. | `32` | The format in which the image data is sent.
| `t` | Single character. `(d, f, t, s)`. | `d` | The transmission medium used. | `t` | Single character. `(d, f, t, s)`. | `d` | The transmission medium used.
| `s` | Positive integer. | `0` | The width of the image being sent. | `s` | Positive integer. | `0` | The width of the image being sent.
@@ -215,7 +251,18 @@ take, and the default value they take when missing.
| `S` | Positive integer. | `0` | The size of data to read from a file. | `S` | Positive integer. | `0` | The size of data to read from a file.
| `O` | Positive integer. | `0` | The offset from which to read data from a file. | `O` | Positive integer. | `0` | The offset from which to read data from a file.
| `i` | Positive integer. `(0 - 4294967295)` | `0` | The image id | `i` | Positive integer. `(0 - 4294967295)` | `0` | The image id
| `o` | Single character. `only z` | - | The type of data compression. | `o` | Single character. `only z` | null | The type of data compression.
| `m` | zero or one | `0` | Whether there is more chunked data available. | `m` | zero or one | `0` | Whether there is more chunked data available.
4+^h| Keys for image display
| `x` | Positive integer | `0` | The left edge (in pixels) of the image area to display
| `y` | Positive integer | `0` | The top edge (in pixels) of the image area to display
| `w` | Positive integer | `0` | The width (in pixels) of the image area to display. By default, the entire width is used.
| `h` | Positive integer | `0` | The height (in pixels) of the image area to display. By default, the entire height is used
| `X` | Positive integer | `0` | The x-offset within the first cell at which to start displaying the image
| `Y` | Positive integer | `0` | The y-offset within the first cell at which to start displaying the image
| `c` | Positive integer | `0` | The number of columns to display the image over
| `r` | Positive integer | `0` | The number of rows to display the image over
| `z` | Integer | `0` | The *z-index* vertical stacking order of the image
|=== |===