[PATCH weston 2/2] compositor: Add doxygen for weston_surface_to_buffer_rect()

[Derek Foreman]

Signed-off-by: Derek Foreman <derekf at osg.samsung.com>
---
 src/compositor.c | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/compositor.c b/src/compositor.c
index 0118b67..43cd094 100644
--- a/src/compositor.c
+++ b/src/compositor.c
@@ -932,6 +932,24 @@ weston_surface_to_buffer(struct weston_surface *surface,
 	*by = floorf(byf);
 }
 
+/* Transform a rectangle from surface coordinates to buffer coordinates
+ *
+ * \param surface The surface to fetch wl_viewport and buffer transformation
+ * from.
+ * \param rect The rectangle to transform.
+ * \return The transformed rectangle.
+ *
+ * Viewport and buffer transformations can only do translation, scaling,
+ * and rotations in 90-degree steps. Therefore the only loss in the
+ * conversion is coordinate rounding.
+ *
+ * However, some coordinate rounding takes place as an intermediate
+ * step before the buffer scale factor is applied, so the rectangle
+ * boundary may not be exactly as expected.
+ *
+ * This is OK for damage tracking since a little extra coverage is
+ * not a problem.
+ */
 WL_EXPORT pixman_box32_t
 weston_surface_to_buffer_rect(struct weston_surface *surface,
 			      pixman_box32_t rect)
@@ -965,7 +983,8 @@ weston_surface_to_buffer_rect(struct weston_surface *surface,
  *
  * Viewport and buffer transformations can only do translation, scaling,
  * and rotations in 90-degree steps. Therefore the only loss in the
- * conversion is coordinate flooring (rounding).
+ * conversion is from the coordinate rounding that takes place in
+ * \ref weston_surface_to_buffer_rect.
  */
 WL_EXPORT void
 weston_surface_to_buffer_region(struct weston_surface *surface,
-- 
2.6.2