[PATCH weston] compositor: document weston_view_damage_below()

[Pekka Paalanen]

From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>

Explains what weston_view::clip is.

Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
---
 src/compositor.c | 16 ++++++++++++++++
 src/compositor.h |  2 +-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/src/compositor.c b/src/compositor.c
index 9e2bd80..d408ccb 100644
--- a/src/compositor.c
+++ b/src/compositor.c
@@ -943,6 +943,22 @@ weston_view_move_to_plane(struct weston_view *view,
 	weston_surface_damage(view->surface);
 }
 
+/** Inflict damage on the plane where the view is visible.
+ *
+ * \param view The view that causes the damage.
+ *
+ * If the view is currently on a plane (including the primary plane),
+ * take the view's boundingbox, subtract all the opaque views that cover it,
+ * and add the remaining region as damage to the plane. This corresponds
+ * to the damage inflicted to the plane if this view disappeared.
+ *
+ * A repaint is scheduled for this view.
+ *
+ * The region of all opaque views covering this view is stored in
+ * weston_view::clip and updated by view_accumulate_damage() during
+ * weston_output_repaint(). Specifically, that region matches the
+ * scenegraph as it was last painted.
+ */
 WL_EXPORT void
 weston_view_damage_below(struct weston_view *view)
 {
diff --git a/src/compositor.h b/src/compositor.h
index 5c3ee2f..fa79569 100644
--- a/src/compositor.h
+++ b/src/compositor.h
@@ -764,7 +764,7 @@ struct weston_view {
 	struct weston_plane *plane;
 	struct weston_view *parent_view;
 
-	pixman_region32_t clip;
+	pixman_region32_t clip;          /* See weston_view_damage_below() */
 	float alpha;                     /* part of geometry, see below */
 
 	void *renderer_state;
-- 
2.0.5