dep/sdl/include/SDL_rect.h

   1 /*
   2   Simple DirectMedia Layer
   3   Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
   4
   5   This software is provided 'as-is', without any express or implied
   6   warranty.  In no event will the authors be held liable for any damages
   7   arising from the use of this software.
   8
   9   Permission is granted to anyone to use this software for any purpose,
  10   including commercial applications, and to alter it and redistribute it
  11   freely, subject to the following restrictions:
  12
  13   1. The origin of this software must not be misrepresented; you must not
  14      claim that you wrote the original software. If you use this software
  15      in a product, an acknowledgment in the product documentation would be
  16      appreciated but is not required.
  17   2. Altered source versions must be plainly marked as such, and must not be
  18      misrepresented as being the original software.
  19   3. This notice may not be removed or altered from any source distribution.
  20 */
  21
  22 /**
  23  *  \file SDL_rect.h
  24  *
  25  *  Header file for SDL_rect definition and management functions.
  26  */
  27
  28 #ifndef SDL_rect_h_
  29 #define SDL_rect_h_
  30
  31 #include "SDL_stdinc.h"
  32 #include "SDL_error.h"
  33 #include "SDL_pixels.h"
  34 #include "SDL_rwops.h"
  35
  36 #include "begin_code.h"
  37 /* Set up for C function definitions, even when using C++ */
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 /**
  43  * The structure that defines a point (integer)
  44  *
  45  * \sa SDL_EnclosePoints
  46  * \sa SDL_PointInRect
  47  */
  48 typedef struct SDL_Point
  49 {
  50     int x;
  51     int y;
  52 } SDL_Point;
  53
  54 /**
  55  * The structure that defines a point (floating point)
  56  *
  57  * \sa SDL_EncloseFPoints
  58  * \sa SDL_PointInFRect
  59  */
  60 typedef struct SDL_FPoint
  61 {
  62     float x;
  63     float y;
  64 } SDL_FPoint;
  65
  66
  67 /**
  68  * A rectangle, with the origin at the upper left (integer).
  69  *
  70  * \sa SDL_RectEmpty
  71  * \sa SDL_RectEquals
  72  * \sa SDL_HasIntersection
  73  * \sa SDL_IntersectRect
  74  * \sa SDL_IntersectRectAndLine
  75  * \sa SDL_UnionRect
  76  * \sa SDL_EnclosePoints
  77  */
  78 typedef struct SDL_Rect
  79 {
  80     int x, y;
  81     int w, h;
  82 } SDL_Rect;
  83
  84
  85 /**
  86  * A rectangle, with the origin at the upper left (floating point).
  87  *
  88  * \sa SDL_FRectEmpty
  89  * \sa SDL_FRectEquals
  90  * \sa SDL_FRectEqualsEpsilon
  91  * \sa SDL_HasIntersectionF
  92  * \sa SDL_IntersectFRect
  93  * \sa SDL_IntersectFRectAndLine
  94  * \sa SDL_UnionFRect
  95  * \sa SDL_EncloseFPoints
  96  * \sa SDL_PointInFRect
  97  */
  98 typedef struct SDL_FRect
  99 {
 100     float x;
 101     float y;
 102     float w;
 103     float h;
 104 } SDL_FRect;
 105
 106
 107 /**
 108  * Returns true if point resides inside a rectangle.
 109  */
 110 SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
 111 {
 112     return ( (p->x >= r->x) && (p->x < (r->x + r->w)) &&
 113              (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE;
 114 }
 115
 116 /**
 117  * Returns true if the rectangle has no area.
 118  */
 119 SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
 120 {
 121     return ((!r) || (r->w <= 0) || (r->h <= 0)) ? SDL_TRUE : SDL_FALSE;
 122 }
 123
 124 /**
 125  * Returns true if the two rectangles are equal.
 126  */
 127 SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
 128 {
 129     return (a && b && (a->x == b->x) && (a->y == b->y) &&
 130             (a->w == b->w) && (a->h == b->h)) ? SDL_TRUE : SDL_FALSE;
 131 }
 132
 133 /**
 134  * Determine whether two rectangles intersect.
 135  *
 136  * If either pointer is NULL the function will return SDL_FALSE.
 137  *
 138  * \param A an SDL_Rect structure representing the first rectangle
 139  * \param B an SDL_Rect structure representing the second rectangle
 140  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
 141  *
 142  * \since This function is available since SDL 2.0.0.
 143  *
 144  * \sa SDL_IntersectRect
 145  */
 146 extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A,
 147                                                      const SDL_Rect * B);
 148
 149 /**
 150  * Calculate the intersection of two rectangles.
 151  *
 152  * If `result` is NULL then this function will return SDL_FALSE.
 153  *
 154  * \param A an SDL_Rect structure representing the first rectangle
 155  * \param B an SDL_Rect structure representing the second rectangle
 156  * \param result an SDL_Rect structure filled in with the intersection of
 157  *               rectangles `A` and `B`
 158  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
 159  *
 160  * \since This function is available since SDL 2.0.0.
 161  *
 162  * \sa SDL_HasIntersection
 163  */
 164 extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A,
 165                                                    const SDL_Rect * B,
 166                                                    SDL_Rect * result);
 167
 168 /**
 169  * Calculate the union of two rectangles.
 170  *
 171  * \param A an SDL_Rect structure representing the first rectangle
 172  * \param B an SDL_Rect structure representing the second rectangle
 173  * \param result an SDL_Rect structure filled in with the union of rectangles
 174  *               `A` and `B`
 175  *
 176  * \since This function is available since SDL 2.0.0.
 177  */
 178 extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A,
 179                                            const SDL_Rect * B,
 180                                            SDL_Rect * result);
 181
 182 /**
 183  * Calculate a minimal rectangle enclosing a set of points.
 184  *
 185  * If `clip` is not NULL then only points inside of the clipping rectangle are
 186  * considered.
 187  *
 188  * \param points an array of SDL_Point structures representing points to be
 189  *               enclosed
 190  * \param count the number of structures in the `points` array
 191  * \param clip an SDL_Rect used for clipping or NULL to enclose all points
 192  * \param result an SDL_Rect structure filled in with the minimal enclosing
 193  *               rectangle
 194  * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
 195  *          points were outside of the clipping rectangle.
 196  *
 197  * \since This function is available since SDL 2.0.0.
 198  */
 199 extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points,
 200                                                    int count,
 201                                                    const SDL_Rect * clip,
 202                                                    SDL_Rect * result);
 203
 204 /**
 205  * Calculate the intersection of a rectangle and line segment.
 206  *
 207  * This function is used to clip a line segment to a rectangle. A line segment
 208  * contained entirely within the rectangle or that does not intersect will
 209  * remain unchanged. A line segment that crosses the rectangle at either or
 210  * both ends will be clipped to the boundary of the rectangle and the new
 211  * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
 212  *
 213  * \param rect an SDL_Rect structure representing the rectangle to intersect
 214  * \param X1 a pointer to the starting X-coordinate of the line
 215  * \param Y1 a pointer to the starting Y-coordinate of the line
 216  * \param X2 a pointer to the ending X-coordinate of the line
 217  * \param Y2 a pointer to the ending Y-coordinate of the line
 218  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
 219  *
 220  * \since This function is available since SDL 2.0.0.
 221  */
 222 extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRectAndLine(const SDL_Rect *
 223                                                           rect, int *X1,
 224                                                           int *Y1, int *X2,
 225                                                           int *Y2);
 226
 227
 228 /* SDL_FRect versions... */
 229
 230 /**
 231  * Returns true if point resides inside a rectangle.
 232  */
 233 SDL_FORCE_INLINE SDL_bool SDL_PointInFRect(const SDL_FPoint *p, const SDL_FRect *r)
 234 {
 235     return ( (p->x >= r->x) && (p->x < (r->x + r->w)) &&
 236              (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE;
 237 }
 238
 239 /**
 240  * Returns true if the rectangle has no area.
 241  */
 242 SDL_FORCE_INLINE SDL_bool SDL_FRectEmpty(const SDL_FRect *r)
 243 {
 244     return ((!r) || (r->w <= 0.0f) || (r->h <= 0.0f)) ? SDL_TRUE : SDL_FALSE;
 245 }
 246
 247 /**
 248  * Returns true if the two rectangles are equal, within some given epsilon.
 249  *
 250  * \since This function is available since SDL 2.0.22.
 251  */
 252 SDL_FORCE_INLINE SDL_bool SDL_FRectEqualsEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon)
 253 {
 254     return (a && b && ((a == b) ||
 255             ((SDL_fabsf(a->x - b->x) <= epsilon) &&
 256             (SDL_fabsf(a->y - b->y) <= epsilon) &&
 257             (SDL_fabsf(a->w - b->w) <= epsilon) &&
 258             (SDL_fabsf(a->h - b->h) <= epsilon))))
 259             ? SDL_TRUE : SDL_FALSE;
 260 }
 261
 262 /**
 263  * Returns true if the two rectangles are equal, using a default epsilon.
 264  *
 265  * \since This function is available since SDL 2.0.22.
 266  */
 267 SDL_FORCE_INLINE SDL_bool SDL_FRectEquals(const SDL_FRect *a, const SDL_FRect *b)
 268 {
 269     return SDL_FRectEqualsEpsilon(a, b, SDL_FLT_EPSILON);
 270 }
 271
 272 /**
 273  * Determine whether two rectangles intersect with float precision.
 274  *
 275  * If either pointer is NULL the function will return SDL_FALSE.
 276  *
 277  * \param A an SDL_FRect structure representing the first rectangle
 278  * \param B an SDL_FRect structure representing the second rectangle
 279  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
 280  *
 281  * \since This function is available since SDL 2.0.22.
 282  *
 283  * \sa SDL_IntersectRect
 284  */
 285 extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersectionF(const SDL_FRect * A,
 286                                                       const SDL_FRect * B);
 287
 288 /**
 289  * Calculate the intersection of two rectangles with float precision.
 290  *
 291  * If `result` is NULL then this function will return SDL_FALSE.
 292  *
 293  * \param A an SDL_FRect structure representing the first rectangle
 294  * \param B an SDL_FRect structure representing the second rectangle
 295  * \param result an SDL_FRect structure filled in with the intersection of
 296  *               rectangles `A` and `B`
 297  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
 298  *
 299  * \since This function is available since SDL 2.0.22.
 300  *
 301  * \sa SDL_HasIntersectionF
 302  */
 303 extern DECLSPEC SDL_bool SDLCALL SDL_IntersectFRect(const SDL_FRect * A,
 304                                                     const SDL_FRect * B,
 305                                                     SDL_FRect * result);
 306
 307 /**
 308  * Calculate the union of two rectangles with float precision.
 309  *
 310  * \param A an SDL_FRect structure representing the first rectangle
 311  * \param B an SDL_FRect structure representing the second rectangle
 312  * \param result an SDL_FRect structure filled in with the union of rectangles
 313  *               `A` and `B`
 314  *
 315  * \since This function is available since SDL 2.0.22.
 316  */
 317 extern DECLSPEC void SDLCALL SDL_UnionFRect(const SDL_FRect * A,
 318                                             const SDL_FRect * B,
 319                                             SDL_FRect * result);
 320
 321 /**
 322  * Calculate a minimal rectangle enclosing a set of points with float
 323  * precision.
 324  *
 325  * If `clip` is not NULL then only points inside of the clipping rectangle are
 326  * considered.
 327  *
 328  * \param points an array of SDL_FPoint structures representing points to be
 329  *               enclosed
 330  * \param count the number of structures in the `points` array
 331  * \param clip an SDL_FRect used for clipping or NULL to enclose all points
 332  * \param result an SDL_FRect structure filled in with the minimal enclosing
 333  *               rectangle
 334  * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
 335  *          points were outside of the clipping rectangle.
 336  *
 337  * \since This function is available since SDL 2.0.22.
 338  */
 339 extern DECLSPEC SDL_bool SDLCALL SDL_EncloseFPoints(const SDL_FPoint * points,
 340                                                     int count,
 341                                                     const SDL_FRect * clip,
 342                                                     SDL_FRect * result);
 343
 344 /**
 345  * Calculate the intersection of a rectangle and line segment with float
 346  * precision.
 347  *
 348  * This function is used to clip a line segment to a rectangle. A line segment
 349  * contained entirely within the rectangle or that does not intersect will
 350  * remain unchanged. A line segment that crosses the rectangle at either or
 351  * both ends will be clipped to the boundary of the rectangle and the new
 352  * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
 353  *
 354  * \param rect an SDL_FRect structure representing the rectangle to intersect
 355  * \param X1 a pointer to the starting X-coordinate of the line
 356  * \param Y1 a pointer to the starting Y-coordinate of the line
 357  * \param X2 a pointer to the ending X-coordinate of the line
 358  * \param Y2 a pointer to the ending Y-coordinate of the line
 359  * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
 360  *
 361  * \since This function is available since SDL 2.0.22.
 362  */
 363 extern DECLSPEC SDL_bool SDLCALL SDL_IntersectFRectAndLine(const SDL_FRect *
 364                                                            rect, float *X1,
 365                                                            float *Y1, float *X2,
 366                                                            float *Y2);
 367
 368 /* Ends C function definitions when using C++ */
 369 #ifdef __cplusplus
 370 }
 371 #endif
 372 #include "close_code.h"
 373
 374 #endif /* SDL_rect_h_ */
 375
 376 /* vi: set ts=4 sw=4 expandtab: */