for_each_surface: only iterate mapped surfaces

These functions are used mostly for rendering, where including unmapped
surfaces is undesired.

This is a breaking change. However, few to no usages will have to be
updated.

3 files changed, 15 insertions, 10 deletions

diff --git a/include/wlr/types/wlr_layer_shell_v1.h b/include/wlr/types/wlr_layer_shell_v1.h
index 7786779e..694fb3b2 100644
--- a/include/wlr/types/wlr_layer_shell_v1.h
+++ b/include/wlr/types/wlr_layer_shell_v1.h
@@ -143,7 +143,10 @@ bool wlr_surface_is_layer_surface(struct wlr_surface *surface);
 struct wlr_layer_surface_v1 *wlr_layer_surface_v1_from_wlr_surface(
 		struct wlr_surface *surface);
 
-/* Calls the iterator function for each sub-surface and popup of this surface */
+/**
+ * Calls the iterator function for each mapped sub-surface and popup of this
+ * surface (whether or not this surface is mapped).
+ */
 void wlr_layer_surface_v1_for_each_surface(struct wlr_layer_surface_v1 *surface,
 		wlr_surface_iterator_func_t iterator, void *user_data);
 
diff --git a/include/wlr/types/wlr_surface.h b/include/wlr/types/wlr_surface.h
index d743415f..f33ac5b1 100644
--- a/include/wlr/types/wlr_surface.h
+++ b/include/wlr/types/wlr_surface.h
@@ -264,9 +264,9 @@ void wlr_surface_get_extends(struct wlr_surface *surface, struct wlr_box *box);
 struct wlr_surface *wlr_surface_from_resource(struct wl_resource *resource);
 
 /**
- * Call `iterator` on each surface in the surface tree, with the surface's
- * position relative to the root surface. The function is called from root to
- * leaves (in rendering order).
+ * Call `iterator` on each mapped surface in the surface tree (whether or not
+ * this surface is mapped), with the surface's position relative to the root
+ * surface. The function is called from root to leaves (in rendering order).
  */
 void wlr_surface_for_each_surface(struct wlr_surface *surface,
 	wlr_surface_iterator_func_t iterator, void *user_data);
diff --git a/include/wlr/types/wlr_xdg_shell.h b/include/wlr/types/wlr_xdg_shell.h
index d63132c4..cf42e82a 100644
--- a/include/wlr/types/wlr_xdg_shell.h
+++ b/include/wlr/types/wlr_xdg_shell.h
@@ -413,17 +413,19 @@ void wlr_xdg_surface_get_geometry(struct wlr_xdg_surface *surface,
 		struct wlr_box *box);
 
 /**
- * Call `iterator` on each surface and popup in the xdg-surface tree, with the
- * surface's position relative to the root xdg-surface. The function is called
- * from root to leaves (in rendering order).
+ * Call `iterator` on each mapped surface and popup in the xdg-surface tree
+ * (whether or not this xdg-surface is mapped), with the surface's position
+ * relative to the root xdg-surface. The function is called from root to leaves
+ * (in rendering order).
  */
 void wlr_xdg_surface_for_each_surface(struct wlr_xdg_surface *surface,
 		wlr_surface_iterator_func_t iterator, void *user_data);
 
 /**
- * Call `iterator` on each popup's surface and popup's subsurface in the
- * xdg-surface tree, with the surfaces's position relative to the root
- * xdg-surface. The function is called from root to leaves (in rendering order).
+ * Call `iterator` on each mapped popup's surface and popup's subsurface in the
+ * xdg-surface tree (whether or not this xdg-surface is mapped), with the
+ * surfaces's position relative to the root xdg-surface. The function is called
+ * from root to leaves (in rendering order).
  */
 void wlr_xdg_surface_for_each_popup_surface(struct wlr_xdg_surface *surface,
 		wlr_surface_iterator_func_t iterator, void *user_data);