Send ACKs to client when displaying images by id

graphics-protocol.asciidoc

@@ -177,7 +177,7 @@ before sending any other graphics related escape codes.
 
 === Detecting available transmission mediums
 
-Since a client has no a-priori knowledge of whether it shares a filesystem/shared emmory
+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 
 (which can be an arbitrary positive integer up to 4294967295, it must not be zero).
 If it does so, the terminal emulator will reply after trying to load the image, saying
@@ -206,7 +206,23 @@ 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.
+cursor position. When specifying an image id, the terminal emulator will reply with an
+acknowledgement code, which will be either:
+
+```
+<ESC>_Gi=<id>;OK<ESC>\
+```
+
+when the image referred to by id was found, or
+
+```
+<ESC>_Gi=<id>;ENOENT:<some detailed error msg><ESC>\
+```
+
+when the image with the specified id was not found. This is similar to the
+scheme described above for querying available transmission media, except that
+here we are querying if the image with the specified id is available or needs to
+be re-transmitted.
 
 === Controlling displayed image layout
 

kitty/graphics.c

@@ -521,9 +521,10 @@ update_src_rect(ImageRef *ref, Image *img) {
 
 static void 
 handle_put_command(GraphicsManager *self, const GraphicsCommand *g, Cursor *c, bool *is_dirty, Image *img) {
+    has_add_respose = false;
     if (img == NULL) img = img_by_client_id(self, g->id);
-    if (img == NULL) { REPORT_ERROR("Put command refers to non-existent image with id: %u", g->id); return; }
-    if (!img->data_loaded) { REPORT_ERROR("Put command refers to image with id: %u that could not load its data", g->id); return; }
+    if (img == NULL) { set_add_response("ENOENT", "Put command refers to non-existent image with id: %u", g->id); return; }
+    if (!img->data_loaded) { set_add_response("ENOENT", "Put command refers to image with id: %u that could not load its data", g->id); return; }
     ensure_space_for(img, refs, ImageRef, img->refcnt + 1, refcap, 10);
     *is_dirty = true;
     self->layers_dirty = true;
@@ -740,6 +741,7 @@ grman_handle_command(GraphicsManager *self, const GraphicsCommand *g, const uint
                 break;
             }
             handle_put_command(self, g, c, is_dirty, NULL);
+            ret = create_add_response(self, g, true);
             break;
         default:
             REPORT_ERROR("Unknown graphics command action: %c", g->action);

kitty_tests/graphics.py

@@ -42,6 +42,12 @@ def send_command(screen, cmd, payload=b''):
     return c.wtcbuf
 
 
+def parse_response(res):
+    if not res:
+        return
+    return res.decode('ascii').partition(';')[2].partition('\033')[0]
+
+
 def load_helpers(self):
     s = self.create_screen()
     g = s.grman
@@ -50,9 +56,7 @@ def load_helpers(self):
         kw.setdefault('i', 1)
         cmd = ','.join('%s=%s' % (k, v) for k, v in kw.items())
         res = send_command(s, cmd, payload)
-        if not res:
-            return
-        return res.decode('ascii').partition(';')[2].partition('\033')[0]
+        return parse_response(res)
 
     def sl(payload, **kw):
         if isinstance(payload, str):
@@ -87,8 +91,8 @@ def put_helpers(self, cw, ch):
         iid += 1
         cmd = 'a=T,f=24,i=%d,s=%d,v=%d,%s' % (iid, w, h, put_cmd(**kw))
         data = b'x' * w * h * 3
-        send_command(screen, cmd, data)
-        return iid
+        res = send_command(screen, cmd, data)
+        return iid, parse_response(res)
 
     def put_ref(screen, **kw):
         cmd = 'a=p,i=%d,%s' % (iid, put_cmd(**kw))
@@ -192,7 +196,7 @@ class TestGraphics(BaseTest):
     def test_image_put(self):
         cw, ch = 10, 20
         s, dx, dy, put_image, put_ref, layers, rect_eq = put_helpers(self, cw, ch)
-        put_image(s, 10, 20)
+        self.ae(put_image(s, 10, 20)[1], 'OK')
         l = layers(s)
         self.ae(len(l), 1)
         rect_eq(l[0]['src_rect'], 0, 0, 1, 1)