KittyPatch/kitty
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

More spec work

Browse Source
This commit is contained in:
Kovid Goyal 2017-01-21 11:30:37 +05:30
parent 832e21cb1d
commit 22a7283420
1 changed files with 94 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
protocol-extensions.asciidoc
View File

@ -14,6 +14,9 @@ toc::[]
kitty supports colored and styled (wavy) underlines. This is of particular use
in terminal editors such as vim and emacs to display red, wavy underlines under
mis-spelled words and/or syntax errors. This is done by re-purposing some SGR escape codes
Setting the width and/or height to zero means that no drawing is done and the
cursor position remains unchanged.
that are not used in modern terminals (https://en.wikipedia.org/wiki/ANSI_escape_code#CSI_codes)
To change the underline style from straight line to curl (this used to be the
@ -96,7 +99,7 @@ The next character `G` indicates this APC code is for graphics data. In the futu
have different first letters for different needs.
The control data is a comma-separated list of key-value pairs with the restriction that
keys and values must contain only the characters `0-9a-zA-Z_-`. The payload is arbitrary binary
keys and values must contain only the characters `0-9a-zA-Z_-+/*`. The payload is arbitrary binary
data interpreted based on the control codes. The binary data must be base-64 encoded so as to minimize
the probability of problems with legacy systems that might interpret control
codes in the binary data incorrectly.
@ -126,6 +129,9 @@ edge of the screen. If the cursor needs to move past the bottom of the screen,
the screen is scrolled. After the entire region is drawn, the cursor will be
positioned at the first cell after the image.
Setting the width and/or height to zero means that no drawing is done and the
cursor position remains unchanged.
==== Transmitting data
@ -161,17 +167,17 @@ take three values, described below:
| f | A simple file
| t | A temporary file, the terminal emulator will delete the file after reading the pixel data
| s | A http://man7.org/linux/man-pages/man7/shm_overview.7.html[POSIX shared memory object]. The terminal emulator will delete it after reading the pixel data from it
| s | A http://man7.org/linux/man-pages/man7/shm_overview.7.html[POSIX shared memory object]. The terminal emulator will delete it after reading the pixel data
|===
In all these cases, the payload data must be the base-64 encoded absolute file path.
An important consideration is how the client can tell if the terminal emulator
[[query]]An important consideration is how the client can tell if the terminal emulator
and it share a filesystem. This can be done by using the _response mode_, specifying
the `q` key, with some unique id as the value. For example,
```
<ESC>_Gt=f,s=100,q=33;<encoded /tmp/pixel_data><ESC>\
<ESC>_Gt=t,s=100,q=33;<encoded /tmp/pixel_data><ESC>\
```
When the terminal emulator receives this escape code, it will read and display
@ -183,6 +189,88 @@ escape code will look like:
<ESC>_Gq=33;<encoded error message or OK><ESC>\
```
Here the q value will be the same as was sent by the client in the original
Here the `q` value will be the same as was sent by the client in the original
request. The payload data will be a base-64 encoded UTF-8 string. The string
will be `OK` if reading the pixel data succeeded or an error message.
will be `OK` if reading the pixel data succeeded or an error message. Clients
can set the width and height to zero to avoid actually drawing anything on
screen during the test.
===== Remote client
Remote clients, those that are unable to use the filesystem/shared memory to
transmit data, must send the pixel data directly using escape codes. Since
escape codes are of limited maximum length, the data will need to be chunked up
for transfer. This is done using the `m` key. The pixel data must first be
base64 encoded then chunked up into chunks no larger than `4096` bytes. The client
then sends the graphics escape code as usual, with the addition os an `m` key that
must have the value `1` for all but the last chunk, where it must be `0`. For example,
if the data is split into three chunks, the client would send the following
sequence of escape codes to the terminal emulator:
```
<ESC>_Gw=100,h=30,s=100,m=1;<base-64 pixel data first chunk><ESC>\
<ESC>_Gm=1;<base-64 pixel data second chunk><ESC>\
<ESC>_Gm=0;<base-64 pixel data last chunk><ESC>\
```
Note that only the first escape code needs to have the full set of control
codes such as stride, width, height, format etc. Subsequent chunks must have
only the `m` key. The client must finish sending all chunks for a single image
before sending any other graphics related escape codes.
=== Image persistence
Full screen applications may need to render the same image multiple times or
even render different parts of an image, in different locations, for example,
if the image is sprite map. Resending the image data each time this happens is
wasteful. Instead this protocol allows the client to have the terminal emulator
manage a persistent store of images.
Persistence is implemented by simply assigning an id to transmitted pixel data using the
key `i`. So for example,
```
<ESC>_Gt=t,s=100,i=some-id;<encoded /tmp/pixel_data><ESC>\
```
Now, if the client wants to redraw that image in the future, all it has to do is send
a code with the keys `t=i,i=some-id`, and no payload, like this:
```
<ESC>_Gt=i,i=some-id;<ESC>\
```
The client can use the `w, h, x, y` keys to draw differnt parts of the image
and draw it at different locations by positioning the cursor before sending the
code.
Saved images can be deleted, to free up resources, by using the code:
```
<ESC>_Gt=d,i=some-id;<ESC>\
```
The special value of 'i=*' will cause the terminal emulator to delete all
stored images. Well behaved clients should send this code before terminating.
Terminal emulators may limit the maximum amount of saved data to avoid DoS
attacks. Terminal emulators should make the limit fairly generous, at least a
few hundred, full screen RGBA images worth of data should be allowed.
Client applications can check if an image is still stored by sending the `q`
key, as described anchor:query[above]. For example,
```
<ESC>_Gt=i,i=some-id,q=some-id;<ESC>\
```
The terminal emulator will respond with:
```
<ESC>_Gq=some-id;<encoded OK or error message><ESC>\
```
If `OK` is sent the image was successfully loaded from the persistent storage, if not,
then it must be resent.