diff --git a/protocol-extensions.asciidoc b/protocol-extensions.asciidoc index 00223dc25..1fa911844 100644 --- a/protocol-extensions.asciidoc +++ b/protocol-extensions.asciidoc @@ -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, ``` -_Gt=f,s=100,q=33;\ +_Gt=t,s=100,q=33;\ ``` When the terminal emulator receives this escape code, it will read and display @@ -183,6 +189,88 @@ escape code will look like: _Gq=33;\ ``` -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: + +``` +_Gw=100,h=30,s=100,m=1;\ +_Gm=1;\ +_Gm=0;\ +``` + +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, + +``` +_Gt=t,s=100,i=some-id;\ +``` + +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: + +``` +_Gt=i,i=some-id;\ +``` + +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: + +``` +_Gt=d,i=some-id;\ +``` + +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, + +``` +_Gt=i,i=some-id,q=some-id;\ +``` + +The terminal emulator will respond with: + +``` +_Gq=some-id;\ +``` + +If `OK` is sent the image was successfully loaded from the persistent storage, if not, +then it must be resent.