From c9e198e02ee1180c8f1d0aca2e27e2dd7f9bf625 Mon Sep 17 00:00:00 2001 From: Fredrick Brennan Date: Sun, 10 May 2020 23:02:12 -0700 Subject: [PATCH] Graphics protocol: note best detection method Per https://github.com/kovidgoyal/kitty/issues/2636#issuecomment-626467852 --- docs/graphics-protocol.rst | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/docs/graphics-protocol.rst b/docs/graphics-protocol.rst index 751d518b7..005e02a94 100644 --- a/docs/graphics-protocol.rst +++ b/docs/graphics-protocol.rst @@ -262,8 +262,8 @@ received. Finally, terminals must not display anything, until the entire sequenc received and validated. -Detecting available transmission mediums -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Querying support and available transmission mediums +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since a client has no a-priori knowledge of whether it shares a filesystem/shared memory with the terminal emulator, it can send an id with the control data, using the ``i`` key @@ -289,6 +289,31 @@ use the *query action*, set ``a=q``. Then the terminal emulator will try to load the image and respond with either OK or an error, as above, but it will not replace an existing image with the same id, nor will it store the image. +While as of May 2020, Kitty is the only terminal emulator to support its +graphics protocol, we intend that any terminal emulator that wishes to support +it can. While one could send `Device Control String (DCS) +`_ +XTGETTCAP TN, this would require that derivatives of Kitty also report a +terminfo name containing at least `kitty`. Therefore, the recommended procedure +for querying support is: + + * Send e.g.:: + + _Gi=31,s=1,v=1,a=q,t=d,f=24;\ + * Immediately after, send anything else that will block the terminal, such as, + perhaps, XTGETTCAP TN (``544e``):: + + P+q544e\ + * See what you get back first. If you get back the XTGETTCAP reply, Kitty + graphics are not supported. If you get the APC reply from Kitty + (``_Gi=31;OK\``), they are. You can therefore query both support + and transmission medium at the same time, as even errors indicate support. + +In order for this detection method to work, Kitty graphics standard-compliant +emulators may handle all escape codes in a first-in-first-out (FIFO) fashion, +but **must** at least always immedidately block upon receiving an APC ``G`` +request with ``a=q``. + Display images on screen -----------------------------