2 files changed, 11 insertions, 2 deletions
diff --git a/include/wlr/types/wlr_output.h b/include/wlr/types/wlr_output.h
index fb21e913..a526b0cf 100644
--- a/include/wlr/types/wlr_output.h
+++ b/include/wlr/types/wlr_output.h
@@ -222,11 +222,16 @@ bool wlr_output_attach_render(struct wlr_output *output, int *buffer_age);
 bool wlr_output_preferred_read_format(struct wlr_output *output,
 	enum wl_shm_format *fmt);
 /**
- * Set the damage region for the frame to be submitted.
+ * Set the damage region for the frame to be submitted. This is the region of
+ * the screen that has changed since the last frame.
  *
  * Compositors implementing damage tracking should call this function with the
  * damaged region in output-buffer-local coordinates (ie. scaled and
  * transformed).
+ *
+ * This region is not to be confused with the renderer's buffer damage, ie. the
+ * region compositors need to repaint. Compositors usually need to repaint more
+ * than what changed since last frame since multiple render buffers are used.
  */
 void wlr_output_set_damage(struct wlr_output *output,
 	pixman_region32_t *damage);
diff --git a/include/wlr/types/wlr_output_damage.h b/include/wlr/types/wlr_output_damage.h
index 43db717b..708ee9b6 100644
--- a/include/wlr/types/wlr_output_damage.h
+++ b/include/wlr/types/wlr_output_damage.h
@@ -66,9 +66,13 @@ void wlr_output_damage_destroy(struct wlr_output_damage *output_damage);
  * `needs_frame` will be set to true if a frame should be submitted. `damage`
  * will be set to the region of the output that needs to be repainted, in
  * output-buffer-local coordinates.
+ *
+ * The buffer damage region accumulates all damage since the buffer has last
+ * been swapped. This is not to be confused with the output surface damage,
+ * which only contains the changes between two frames.
  */
 bool wlr_output_damage_attach_render(struct wlr_output_damage *output_damage,
-	bool *needs_frame, pixman_region32_t *damage);
+	bool *needs_frame, pixman_region32_t *buffer_damage);
 /**
  * Accumulates damage and schedules a `frame` event.
  */