From d47efb77506e1dc8eafc0de085dcef685ebf6c09 Mon Sep 17 00:00:00 2001
From: Sergei Grechanik <sergei.grechanik@gmail.com>
Date: Sat, 31 Dec 2022 12:05:12 -0800
Subject: [PATCH] [Unicode placeholders] Fix some filter functions, fix docs

---
 docs/graphics-protocol.rst | 17 ++++++++++++-----
 kitty/graphics.c           | 17 +++++++++--------
 2 files changed, 21 insertions(+), 13 deletions(-)

diff --git a/docs/graphics-protocol.rst b/docs/graphics-protocol.rst
index da21392030..2b2bf6b671 100644
--- a/docs/graphics-protocol.rst
+++ b/docs/graphics-protocol.rst
@@ -489,11 +489,18 @@ This will not work for horizontal scrolling and overlapping images since the two
 given rules will fail to guess the missing information. In such cases, the
 terminal may apply other heuristics (but it doesn't have to).
 
-Placement deletion commands do not affect images displayed using Unicode
-placeholders, unless it deletes the virtual placement or the image itself. A
-virtual placement may be deleted only when the `d` key is equal to ``i``, ``I``,
-``n`` or ``N``. The key values ``a``, ``c``, ``p``, ``q``, ``x``, ``y``, ``z``
-and their capital variants never affect virtual placements.
+It is important to distinguish between virtual image placements and real images
+displayed on top of placeholders. Virtual placements are invisible and only play
+the role of prototypes for real images. Virtual placements can be deleted by a
+deletion command only when the `d` key is equal to ``i``, ``I``, ``n`` or ``N``.
+The key values ``a``, ``c``, ``p``, ``q``, ``x``, ``y``, ``z`` and their capital
+variants never affect virtual placements because they do not have a physical
+location on the screen.
+
+Real images displayed on top of placeholders are not considered placements from
+the protocol perspective. They cannot be manipulated using graphics commands,
+instead they should be moved, deleted, or modified by manipulating the
+underlying placeholder as normal text.
 
 
 Deleting images
diff --git a/kitty/graphics.c b/kitty/graphics.c
index 1f35722907..c6615b2c95 100644
--- a/kitty/graphics.c
+++ b/kitty/graphics.c
@@ -1590,8 +1590,7 @@ modify_refs(GraphicsManager *self, const void* data, bool (*filter_func)(ImageRe
 
 static bool
 scroll_filter_func(ImageRef *ref, Image UNUSED *img, const void *data, CellPixelSize cell UNUSED) {
-    if (ref->is_virtual_ref)
-        return false;
+    if (ref->is_virtual_ref) return false;
     ScrollData *d = (ScrollData*)data;
     ref->start_row += d->amt;
     return ref->start_row + (int32_t)ref->effective_num_rows <= d->limit;
@@ -1609,8 +1608,7 @@ ref_outside_region(const ImageRef *ref, index_type margin_top, index_type margin
 
 static bool
 scroll_filter_margins_func(ImageRef* ref, Image* img, const void* data, CellPixelSize cell) {
-    if (ref->is_virtual_ref)
-        return false;
+    if (ref->is_virtual_ref) return false;
     ScrollData *d = (ScrollData*)data;
     if (ref_within_region(ref, d->margin_top, d->margin_bottom)) {
         ref->start_row += d->amt;
@@ -1679,15 +1677,13 @@ grman_remove_all_cell_images(GraphicsManager *self) {
 
 static bool
 clear_filter_func(const ImageRef *ref, Image UNUSED *img, const void UNUSED *data, CellPixelSize cell UNUSED) {
-    if (ref->is_virtual_ref)
-        return false;
+    if (ref->is_virtual_ref || ref->is_cell_image) return false;
     return ref->start_row + (int32_t)ref->effective_num_rows > 0;
 }
 
 static bool
 clear_all_filter_func(const ImageRef *ref UNUSED, Image UNUSED *img, const void UNUSED *data, CellPixelSize cell UNUSED) {
-    if (ref->is_virtual_ref)
-        return false;
+    if (ref->is_virtual_ref) return false;
     return true;
 }
 
@@ -1713,18 +1709,21 @@ number_filter_func(const ImageRef *ref, Image *img, const void *data, CellPixelS
 
 static bool
 x_filter_func(const ImageRef *ref, Image UNUSED *img, const void *data, CellPixelSize cell UNUSED) {
+    if (ref->is_virtual_ref || ref->is_cell_image) return false;
     const GraphicsCommand *g = data;
     return ref->start_column <= (int32_t)g->x_offset - 1 && ((int32_t)g->x_offset - 1) < ((int32_t)(ref->start_column + ref->effective_num_cols));
 }
 
 static bool
 y_filter_func(const ImageRef *ref, Image UNUSED *img, const void *data, CellPixelSize cell UNUSED) {
+    if (ref->is_virtual_ref || ref->is_cell_image) return false;
     const GraphicsCommand *g = data;
     return ref->start_row <= (int32_t)g->y_offset - 1 && ((int32_t)g->y_offset - 1) < ((int32_t)(ref->start_row + ref->effective_num_rows));
 }
 
 static bool
 z_filter_func(const ImageRef *ref, Image UNUSED *img, const void *data, CellPixelSize cell UNUSED) {
+    if (ref->is_virtual_ref || ref->is_cell_image) return false;
     const GraphicsCommand *g = data;
     return ref->z_index == g->z_index;
 }
@@ -1732,11 +1731,13 @@ z_filter_func(const ImageRef *ref, Image UNUSED *img, const void *data, CellPixe
 
 static bool
 point_filter_func(const ImageRef *ref, Image *img, const void *data, CellPixelSize cell) {
+    if (ref->is_virtual_ref || ref->is_cell_image) return false;
     return x_filter_func(ref, img, data, cell) && y_filter_func(ref, img, data, cell);
 }
 
 static bool
 point3d_filter_func(const ImageRef *ref, Image *img, const void *data, CellPixelSize cell) {
+    if (ref->is_virtual_ref || ref->is_cell_image) return false;
     return z_filter_func(ref, img, data, cell) && point_filter_func(ref, img, data, cell);
 }