diff options
Diffstat (limited to 'include/wlr')
-rw-r--r-- | include/wlr/util/box.h | 59 |
1 files changed, 49 insertions, 10 deletions
diff --git a/include/wlr/util/box.h b/include/wlr/util/box.h index 2a407c4d..5be2cdc1 100644 --- a/include/wlr/util/box.h +++ b/include/wlr/util/box.h @@ -1,40 +1,79 @@ /* - * This an unstable interface of wlroots. No guarantees are made regarding the - * future consistency of this API. +* This is a stable interface of wlroots. Future changes will be limited to: + * + * - New functions + * - New struct members + * - New enum members + * + * Note that wlroots does not make an ABI compatibility promise - in the future, + * the layout and size of structs used by wlroots may change, requiring code + * depending on this header to be recompiled (but not edited). + * + * Breaking changes are announced in the release notes and follow a 1-year + * deprecation schedule. */ -#ifndef WLR_USE_UNSTABLE -#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features" -#endif - -#ifndef WLR_TYPES_WLR_BOX_H -#define WLR_TYPES_WLR_BOX_H +#ifndef WLR_UTIL_BOX_H +#define WLR_UTIL_BOX_H -#include <pixman.h> #include <stdbool.h> #include <wayland-server-protocol.h> +/** + * A box representing a rectangle region in a 2D space. + * + * The x and y coordinates are inclusive, and the width and height lengths are + * exclusive. In other words, the box starts from the coordinates (x, y), and + * goes up to but not including (x + width, y + height) + */ struct wlr_box { int x, y; int width, height; }; +/** + * A floating-point box representing a rectangle region in a 2D space. + * + * wlr_fbox has the same semantics as wlr_box + */ struct wlr_fbox { double x, y; double width, height; }; +/** + * Finds the closest point within the box bounds + * + * Returns NAN if the box is empty + */ void wlr_box_closest_point(const struct wlr_box *box, double x, double y, double *dest_x, double *dest_y); +/** + * Gives the intersecting box betweem two wlr_box. + * + * Returns an empty wlr_box if the provided wlr_box don't intersect. + */ bool wlr_box_intersection(struct wlr_box *dest, const struct wlr_box *box_a, const struct wlr_box *box_b); +/** + * Verifies if a point is contained within the bounds of a given wlr_box. + * + * For example: + * - A point at (100, 50) is not contained in the box (0, 0, 100, 50). + * - A point at (10, 10) is contained in the box (10, 0, 50, 50). + */ bool wlr_box_contains_point(const struct wlr_box *box, double x, double y); +/** + * Checks whether a box is empty or not. + * + * A wlr_box is considered empty if its width and/or height is zero or negative. + */ bool wlr_box_empty(const struct wlr_box *box); /** - * Transforms a box inside a `width` x `height` box. + * Transforms a box inside a (0, 0, width, height) box. */ void wlr_box_transform(struct wlr_box *dest, const struct wlr_box *box, enum wl_output_transform transform, int width, int height); |