region: add docs for wlr_region_scale_xy() and wlr_region_confine()

1 files changed, 21 insertions, 2 deletions

diff --git a/include/wlr/util/region.h b/include/wlr/util/region.h
index 948307a1..ccd926fd 100644
--- a/include/wlr/util/region.h
+++ b/include/wlr/util/region.h
@@ -21,14 +21,26 @@
 #include <wayland-server-protocol.h>
 
 /**
- * Scales a region, ie. multiplies all its coordinates by `scale`.
+ * Scale a region by the specified factor.
  *
  * The resulting coordinates are rounded up or down so that the new region is
- * at least as big as the original one.
+ * at least as big as the original one if the scale factor is greater or equal
+ * to 1.
+ *
+ * Also see wlr_region_scale_xy().
  */
 void wlr_region_scale(pixman_region32_t *dst, const pixman_region32_t *src,
 	float scale);
 
+/**
+ * Scale a region by the specified factors.
+ *
+ * The X and Y coordinates are scaled separately by scale_x and scale_y.
+ *
+ * The resulting coordinates are rounded up or down so that the new region is
+ * at least as big as the original one if the scale factor is greater or equal
+ * to 1.
+ */
 void wlr_region_scale_xy(pixman_region32_t *dst, const pixman_region32_t *src,
 	float scale_x, float scale_y);
 
@@ -52,6 +64,13 @@ void wlr_region_expand(pixman_region32_t *dst, const pixman_region32_t *src,
 void wlr_region_rotated_bounds(pixman_region32_t *dst, const pixman_region32_t *src,
 	float rotation, int ox, int oy);
 
+/**
+ * Confine a point inside a region.
+ *
+ * x1 and y1 are the old position, x2 and y2 are the new tentative position.
+ * The function returns true with confined coordinates in x2_out and y2_out if
+ * the old position is within the region, or false otherwise.
+ */
 bool wlr_region_confine(const pixman_region32_t *region, double x1, double y1, double x2,
 	double y2, double *x2_out, double *y2_out);