From 9e365069afe156f33fadfad9705e1325f894cd54 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Thu, 9 Dec 2021 20:01:44 +1100 Subject: Cleanup: move public doc-strings into headers for 'blenlib' - Added space below non doc-string comments to make it clear these aren't comments for the symbols directly below them. - Use doxy sections for some headers. - Minor improvements to doc-strings. Ref T92709 --- source/blender/blenlib/BLI_rect.h | 51 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) (limited to 'source/blender/blenlib/BLI_rect.h') diff --git a/source/blender/blenlib/BLI_rect.h b/source/blender/blenlib/BLI_rect.h index 7950596933c..f4b1d051d16 100644 --- a/source/blender/blenlib/BLI_rect.h +++ b/source/blender/blenlib/BLI_rect.h @@ -34,12 +34,28 @@ struct rcti; extern "C" { #endif +/** + * Determine if a `rect` is empty. + * An empty `rect` is one with a zero (or negative) width or height. + * + * \return True if \a rect is empty. + */ bool BLI_rcti_is_empty(const struct rcti *rect); bool BLI_rctf_is_empty(const struct rctf *rect); void BLI_rctf_init(struct rctf *rect, float xmin, float xmax, float ymin, float ymax); void BLI_rcti_init(struct rcti *rect, int xmin, int xmax, int ymin, int ymax); +/** + * Check if X-min and Y-min are less than or equal to X-max and Y-max, respectively. + * If this returns false, #BLI_rctf_sanitize() can be called to address this. + * + * This is not a hard constraint or invariant for rectangles, in some cases it may be useful to + * have max < min. Usually this is what you'd want though. + */ bool BLI_rctf_is_valid(const struct rctf *rect); bool BLI_rcti_is_valid(const struct rcti *rect); +/** + * Ensure X-min and Y-min are less than or equal to X-max and Y-max, respectively. + */ void BLI_rctf_sanitize(struct rctf *rect); void BLI_rcti_sanitize(struct rcti *rect); void BLI_rctf_init_pt_radius(struct rctf *rect, const float xy[2], float size); @@ -50,10 +66,19 @@ void BLI_rcti_do_minmax_v(struct rcti *rect, const int xy[2]); void BLI_rctf_do_minmax_v(struct rctf *rect, const float xy[2]); void BLI_rcti_do_minmax_rcti(struct rcti *rect, const struct rcti *other); +/** + * Given 2 rectangles, transform a point from one to another. + */ void BLI_rctf_transform_pt_v(const rctf *dst, const rctf *src, float xy_dst[2], const float xy_src[2]); +/** + * Calculate a 4x4 matrix representing the transformation between two rectangles. + * + * \note Multiplying a vector by this matrix does *not* + * give the same value as #BLI_rctf_transform_pt_v. + */ void BLI_rctf_transform_calc_m4_pivot_min_ex( const rctf *dst, const rctf *src, float matrix[4][4], uint x, uint y); void BLI_rctf_transform_calc_m4_pivot_min(const rctf *dst, const rctf *src, float matrix[4][4]); @@ -63,7 +88,13 @@ void BLI_rcti_translate(struct rcti *rect, int x, int y); void BLI_rcti_recenter(struct rcti *rect, int x, int y); void BLI_rctf_recenter(struct rctf *rect, float x, float y); void BLI_rcti_resize(struct rcti *rect, int x, int y); +/** + * Change width & height around the central X location. + */ void BLI_rcti_resize_x(struct rcti *rect, int x); +/** + * Change width & height around the central Y location. + */ void BLI_rcti_resize_y(struct rcti *rect, int y); void BLI_rcti_pad(struct rcti *rect, int pad_x, int pad_y); void BLI_rctf_pad(struct rctf *rect, float pad_x, float pad_y); @@ -83,6 +114,14 @@ void BLI_rctf_interp(struct rctf *rect, // void BLI_rcti_interp(struct rctf *rect, struct rctf *rect_a, struct rctf *rect_b, float fac); bool BLI_rctf_clamp_pt_v(const struct rctf *rect, float xy[2]); bool BLI_rcti_clamp_pt_v(const struct rcti *rect, int xy[2]); +/** + * Clamp \a rect within \a rect_bounds, setting \a r_xy to the offset. + * + * Keeps the top left corner within the bounds, which for user interface + * elements is typically where the most important information is. + * + * \return true if a change is made. + */ bool BLI_rctf_clamp(struct rctf *rect, const struct rctf *rect_bounds, float r_xy[2]); bool BLI_rcti_clamp(struct rcti *rect, const struct rcti *rect_bounds, int r_xy[2]); bool BLI_rctf_compare(const struct rctf *rect_a, const struct rctf *rect_b, const float limit); @@ -101,7 +140,13 @@ bool BLI_rctf_isect_x(const rctf *rect, const float x); bool BLI_rctf_isect_y(const rctf *rect, const float y); bool BLI_rctf_isect_pt(const struct rctf *rect, const float x, const float y); bool BLI_rctf_isect_pt_v(const struct rctf *rect, const float xy[2]); +/** + * \returns shortest distance from \a rect to x (0 if inside) + */ int BLI_rcti_length_x(const rcti *rect, const int x); +/** + * \returns shortest distance from \a rect to y (0 if inside) + */ int BLI_rcti_length_y(const rcti *rect, const int y); float BLI_rctf_length_x(const rctf *rect, const float x); float BLI_rctf_length_y(const rctf *rect, const float y); @@ -110,6 +155,9 @@ bool BLI_rctf_isect_segment(const struct rctf *rect, const float s1[2], const fl bool BLI_rcti_isect_circle(const struct rcti *rect, const float xy[2], const float radius); bool BLI_rctf_isect_circle(const struct rctf *rect, const float xy[2], const float radius); bool BLI_rcti_inside_rcti(const rcti *rct_a, const rcti *rct_b); +/** + * is \a rct_b inside \a rct_a + */ bool BLI_rctf_inside_rctf(const rctf *rct_a, const rctf *rct_b); void BLI_rcti_union(struct rcti *rct_a, const struct rcti *rct_b); void BLI_rctf_union(struct rctf *rct_a, const struct rctf *rct_b); @@ -118,6 +166,9 @@ void BLI_rctf_rcti_copy(struct rctf *dst, const struct rcti *src); void BLI_rcti_rctf_copy_floor(struct rcti *dst, const struct rctf *src); void BLI_rcti_rctf_copy_round(struct rcti *dst, const struct rctf *src); +/** + * Expand the rectangle to fit a rotated \a src. + */ void BLI_rctf_rotate_expand(rctf *dst, const rctf *src, const float angle); void print_rctf(const char *str, const struct rctf *rect); -- cgit v1.2.3