SDL 3.0
SDL_rect.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 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 <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_error.h>
33
34#include <SDL3/SDL_begin_code.h>
35/* Set up for C function definitions, even when using C++ */
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/**
41 * The structure that defines a point (using integers).
42 *
43 * \since This struct is available since SDL 3.0.0.
44 *
45 * \sa SDL_GetRectEnclosingPoints
46 * \sa SDL_PointInRect
47 */
48typedef struct SDL_Point
49{
50 int x;
51 int y;
52} SDL_Point;
53
54/**
55 * The structure that defines a point (using floating point values).
56 *
57 * \since This struct is available since SDL 3.0.0.
58 *
59 * \sa SDL_GetRectEnclosingPointsFloat
60 * \sa SDL_PointInRectFloat
61 */
62typedef struct SDL_FPoint
63{
64 float x;
65 float y;
67
68
69/**
70 * A rectangle, with the origin at the upper left (using integers).
71 *
72 * \since This struct is available since SDL 3.0.0.
73 *
74 * \sa SDL_RectEmpty
75 * \sa SDL_RectsEqual
76 * \sa SDL_HasRectIntersection
77 * \sa SDL_GetRectIntersection
78 * \sa SDL_GetRectAndLineIntersection
79 * \sa SDL_GetRectUnion
80 * \sa SDL_GetRectEnclosingPoints
81 */
82typedef struct SDL_Rect
83{
84 int x, y;
85 int w, h;
86} SDL_Rect;
87
88
89/**
90 * A rectangle, with the origin at the upper left (using floating point
91 * values).
92 *
93 * \since This struct is available since SDL 3.0.0.
94 *
95 * \sa SDL_RectEmptyFloat
96 * \sa SDL_RectsEqualFloat
97 * \sa SDL_RectsEqualEpsilon
98 * \sa SDL_HasRectIntersectionFloat
99 * \sa SDL_GetRectIntersectionFloat
100 * \sa SDL_GetRectAndLineIntersectionFloat
101 * \sa SDL_GetRectUnionFloat
102 * \sa SDL_GetRectEnclosingPointsFloat
103 * \sa SDL_PointInRectFloat
104 */
105typedef struct SDL_FRect
106{
107 float x;
108 float y;
109 float w;
110 float h;
111} SDL_FRect;
112
113
114/**
115 * Determine whether a point resides inside a rectangle.
116 *
117 * A point is considered part of a rectangle if both `p` and `r` are not NULL,
118 * and `p`'s x and y coordinates are >= to the rectangle's top left corner,
119 * and < the rectangle's x+w and y+h. So a 1x1 rectangle considers point (0,0)
120 * as "inside" and (0,1) as not.
121 *
122 * Note that this is a forced-inline function in a header, and not a public
123 * API function available in the SDL library (which is to say, the code is
124 * embedded in the calling program and the linker and dynamic loader will not
125 * be able to find this function inside SDL itself).
126 *
127 * \param p the point to test.
128 * \param r the rectangle to test.
129 * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise.
130 *
131 * \threadsafety It is safe to call this function from any thread.
132 *
133 * \since This function is available since SDL 3.0.0.
134 */
136{
137 return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) &&
138 (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE;
139}
140
141/**
142 * Determine whether a rectangle has no area.
143 *
144 * A rectangle is considered "empty" for this function if `r` is NULL, or if
145 * `r`'s width and/or height are <= 0.
146 *
147 * Note that this is a forced-inline function in a header, and not a public
148 * API function available in the SDL library (which is to say, the code is
149 * embedded in the calling program and the linker and dynamic loader will not
150 * be able to find this function inside SDL itself).
151 *
152 * \param r the rectangle to test.
153 * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise.
154 *
155 * \threadsafety It is safe to call this function from any thread.
156 *
157 * \since This function is available since SDL 3.0.0.
158 */
160{
161 return ((!r) || (r->w <= 0) || (r->h <= 0)) ? SDL_TRUE : SDL_FALSE;
162}
163
164/**
165 * Determine whether two rectangles are equal.
166 *
167 * Rectangles are considered equal if both are not NULL and each of their x,
168 * y, width and height match.
169 *
170 * Note that this is a forced-inline function in a header, and not a public
171 * API function available in the SDL library (which is to say, the code is
172 * embedded in the calling program and the linker and dynamic loader will not
173 * be able to find this function inside SDL itself).
174 *
175 * \param a the first rectangle to test.
176 * \param b the second rectangle to test.
177 * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise.
178 *
179 * \threadsafety It is safe to call this function from any thread.
180 *
181 * \since This function is available since SDL 3.0.0.
182 */
184{
185 return (a && b && (a->x == b->x) && (a->y == b->y) &&
186 (a->w == b->w) && (a->h == b->h)) ? SDL_TRUE : SDL_FALSE;
187}
188
189/**
190 * Determine whether two rectangles intersect.
191 *
192 * If either pointer is NULL the function will return SDL_FALSE.
193 *
194 * \param A an SDL_Rect structure representing the first rectangle
195 * \param B an SDL_Rect structure representing the second rectangle
196 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
197 *
198 * \threadsafety It is safe to call this function from any thread.
199 *
200 * \since This function is available since SDL 3.0.0.
201 *
202 * \sa SDL_GetRectIntersection
203 */
204extern DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(const SDL_Rect * A,
205 const SDL_Rect * B);
206
207/**
208 * Calculate the intersection of two rectangles.
209 *
210 * If `result` is NULL then this function will return SDL_FALSE.
211 *
212 * \param A an SDL_Rect structure representing the first rectangle
213 * \param B an SDL_Rect structure representing the second rectangle
214 * \param result an SDL_Rect structure filled in with the intersection of
215 * rectangles `A` and `B`
216 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
217 *
218 * \since This function is available since SDL 3.0.0.
219 *
220 * \sa SDL_HasRectIntersection
221 */
222extern DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect * A,
223 const SDL_Rect * B,
224 SDL_Rect * result);
225
226/**
227 * Calculate the union of two rectangles.
228 *
229 * \param A an SDL_Rect structure representing the first rectangle
230 * \param B an SDL_Rect structure representing the second rectangle
231 * \param result an SDL_Rect structure filled in with the union of rectangles
232 * `A` and `B`
233 * \returns 0 on success or a negative error code on failure; call
234 * SDL_GetError() for more information.
235 *
236 * \since This function is available since SDL 3.0.0.
237 */
238extern DECLSPEC int SDLCALL SDL_GetRectUnion(const SDL_Rect * A,
239 const SDL_Rect * B,
240 SDL_Rect * result);
241
242/**
243 * Calculate a minimal rectangle enclosing a set of points.
244 *
245 * If `clip` is not NULL then only points inside of the clipping rectangle are
246 * considered.
247 *
248 * \param points an array of SDL_Point structures representing points to be
249 * enclosed
250 * \param count the number of structures in the `points` array
251 * \param clip an SDL_Rect used for clipping or NULL to enclose all points
252 * \param result an SDL_Rect structure filled in with the minimal enclosing
253 * rectangle
254 * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
255 * points were outside of the clipping rectangle.
256 *
257 * \since This function is available since SDL 3.0.0.
258 */
259extern DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point * points,
260 int count,
261 const SDL_Rect * clip,
262 SDL_Rect * result);
263
264/**
265 * Calculate the intersection of a rectangle and line segment.
266 *
267 * This function is used to clip a line segment to a rectangle. A line segment
268 * contained entirely within the rectangle or that does not intersect will
269 * remain unchanged. A line segment that crosses the rectangle at either or
270 * both ends will be clipped to the boundary of the rectangle and the new
271 * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
272 *
273 * \param rect an SDL_Rect structure representing the rectangle to intersect
274 * \param X1 a pointer to the starting X-coordinate of the line
275 * \param Y1 a pointer to the starting Y-coordinate of the line
276 * \param X2 a pointer to the ending X-coordinate of the line
277 * \param Y2 a pointer to the ending Y-coordinate of the line
278 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
279 *
280 * \since This function is available since SDL 3.0.0.
281 */
282extern DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *
283 rect, int *X1,
284 int *Y1, int *X2,
285 int *Y2);
286
287
288/* SDL_FRect versions... */
289
290/**
291 * Determine whether a point resides inside a floating point rectangle.
292 *
293 * A point is considered part of a rectangle if both `p` and `r` are not NULL,
294 * and `p`'s x and y coordinates are >= to the rectangle's top left corner,
295 * and < the rectangle's x+w and y+h. So a 1x1 rectangle considers point (0,0)
296 * as "inside" and (0,1) as not.
297 *
298 * Note that this is a forced-inline function in a header, and not a public
299 * API function available in the SDL library (which is to say, the code is
300 * embedded in the calling program and the linker and dynamic loader will not
301 * be able to find this function inside SDL itself).
302 *
303 * \param p the point to test.
304 * \param r the rectangle to test.
305 * \returns SDL_TRUE if `p` is contained by `r`, SDL_FALSE otherwise.
306 *
307 * \threadsafety It is safe to call this function from any thread.
308 *
309 * \since This function is available since SDL 3.0.0.
310 */
312{
313 return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) &&
314 (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE;
315}
316
317/**
318 * Determine whether a floating point rectangle has no area.
319 *
320 * A rectangle is considered "empty" for this function if `r` is NULL, or if
321 * `r`'s width and/or height are <= 0.0f.
322 *
323 * Note that this is a forced-inline function in a header, and not a public
324 * API function available in the SDL library (which is to say, the code is
325 * embedded in the calling program and the linker and dynamic loader will not
326 * be able to find this function inside SDL itself).
327 *
328 * \param r the rectangle to test.
329 * \returns SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise.
330 *
331 * \threadsafety It is safe to call this function from any thread.
332 *
333 * \since This function is available since SDL 3.0.0.
334 */
336{
337 return ((!r) || (r->w <= 0.0f) || (r->h <= 0.0f)) ? SDL_TRUE : SDL_FALSE;
338}
339
340/**
341 * Determine whether two floating point rectangles are equal, within some
342 * given epsilon.
343 *
344 * Rectangles are considered equal if both are not NULL and each of their x,
345 * y, width and height are within `epsilon` of each other. If you don't know
346 * what value to use for `epsilon`, you should call the SDL_RectsEqualFloat
347 * function instead.
348 *
349 * Note that this is a forced-inline function in a header, and not a public
350 * API function available in the SDL library (which is to say, the code is
351 * embedded in the calling program and the linker and dynamic loader will not
352 * be able to find this function inside SDL itself).
353 *
354 * \param a the first rectangle to test.
355 * \param b the second rectangle to test.
356 * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise.
357 *
358 * \threadsafety It is safe to call this function from any thread.
359 *
360 * \since This function is available since SDL 3.0.0.
361 *
362 * \sa SDL_RectsEqualFloat
363 */
364SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon)
365{
366 return (a && b && ((a == b) ||
367 ((SDL_fabsf(a->x - b->x) <= epsilon) &&
368 (SDL_fabsf(a->y - b->y) <= epsilon) &&
369 (SDL_fabsf(a->w - b->w) <= epsilon) &&
370 (SDL_fabsf(a->h - b->h) <= epsilon))))
372}
373
374/**
375 * Determine whether two floating point rectangles are equal, within a default
376 * epsilon.
377 *
378 * Rectangles are considered equal if both are not NULL and each of their x,
379 * y, width and height are within SDL_FLT_EPSILON of each other. This is often
380 * a reasonable way to compare two floating point rectangles and deal with the
381 * slight precision variations in floating point calculations that tend to pop
382 * up.
383 *
384 * Note that this is a forced-inline function in a header, and not a public
385 * API function available in the SDL library (which is to say, the code is
386 * embedded in the calling program and the linker and dynamic loader will not
387 * be able to find this function inside SDL itself).
388 *
389 * \param a the first rectangle to test.
390 * \param b the second rectangle to test.
391 * \returns SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise.
392 *
393 * \threadsafety It is safe to call this function from any thread.
394 *
395 * \since This function is available since SDL 3.0.0.
396 *
397 * \sa SDL_RectsEqualEpsilon
398 */
403
404/**
405 * Determine whether two rectangles intersect with float precision.
406 *
407 * If either pointer is NULL the function will return SDL_FALSE.
408 *
409 * \param A an SDL_FRect structure representing the first rectangle
410 * \param B an SDL_FRect structure representing the second rectangle
411 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
412 *
413 * \since This function is available since SDL 3.0.0.
414 *
415 * \sa SDL_GetRectIntersection
416 */
417extern DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect * A,
418 const SDL_FRect * B);
419
420/**
421 * Calculate the intersection of two rectangles with float precision.
422 *
423 * If `result` is NULL then this function will return SDL_FALSE.
424 *
425 * \param A an SDL_FRect structure representing the first rectangle
426 * \param B an SDL_FRect structure representing the second rectangle
427 * \param result an SDL_FRect structure filled in with the intersection of
428 * rectangles `A` and `B`
429 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
430 *
431 * \since This function is available since SDL 3.0.0.
432 *
433 * \sa SDL_HasRectIntersectionFloat
434 */
435extern DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect * A,
436 const SDL_FRect * B,
437 SDL_FRect * result);
438
439/**
440 * Calculate the union of two rectangles with float precision.
441 *
442 * \param A an SDL_FRect structure representing the first rectangle
443 * \param B an SDL_FRect structure representing the second rectangle
444 * \param result an SDL_FRect structure filled in with the union of rectangles
445 * `A` and `B`
446 * \returns 0 on success or a negative error code on failure; call
447 * SDL_GetError() for more information.
448 *
449 * \since This function is available since SDL 3.0.0.
450 */
451extern DECLSPEC int SDLCALL SDL_GetRectUnionFloat(const SDL_FRect * A,
452 const SDL_FRect * B,
453 SDL_FRect * result);
454
455/**
456 * Calculate a minimal rectangle enclosing a set of points with float
457 * precision.
458 *
459 * If `clip` is not NULL then only points inside of the clipping rectangle are
460 * considered.
461 *
462 * \param points an array of SDL_FPoint structures representing points to be
463 * enclosed
464 * \param count the number of structures in the `points` array
465 * \param clip an SDL_FRect used for clipping or NULL to enclose all points
466 * \param result an SDL_FRect structure filled in with the minimal enclosing
467 * rectangle
468 * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
469 * points were outside of the clipping rectangle.
470 *
471 * \since This function is available since SDL 3.0.0.
472 */
473extern DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint * points,
474 int count,
475 const SDL_FRect * clip,
476 SDL_FRect * result);
477
478/**
479 * Calculate the intersection of a rectangle and line segment with float
480 * precision.
481 *
482 * This function is used to clip a line segment to a rectangle. A line segment
483 * contained entirely within the rectangle or that does not intersect will
484 * remain unchanged. A line segment that crosses the rectangle at either or
485 * both ends will be clipped to the boundary of the rectangle and the new
486 * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
487 *
488 * \param rect an SDL_FRect structure representing the rectangle to intersect
489 * \param X1 a pointer to the starting X-coordinate of the line
490 * \param Y1 a pointer to the starting Y-coordinate of the line
491 * \param X2 a pointer to the ending X-coordinate of the line
492 * \param Y2 a pointer to the ending Y-coordinate of the line
493 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
494 *
495 * \since This function is available since SDL 3.0.0.
496 */
498 rect, float *X1,
499 float *Y1, float *X2,
500 float *Y2);
501
502/* Ends C function definitions when using C++ */
503#ifdef __cplusplus
504}
505#endif
506#include <SDL3/SDL_close_code.h>
507
508#endif /* SDL_rect_h_ */
#define SDL_FORCE_INLINE
SDL_bool SDL_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result)
SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
Definition SDL_rect.h:135
int SDL_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result)
SDL_bool SDL_HasRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B)
SDL_bool SDL_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2)
SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r)
Definition SDL_rect.h:335
SDL_bool SDL_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2)
SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b)
Definition SDL_rect.h:399
SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b)
Definition SDL_rect.h:183
int SDL_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result)
SDL_bool SDL_GetRectIntersectionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result)
SDL_bool SDL_HasRectIntersection(const SDL_Rect *A, const SDL_Rect *B)
SDL_bool SDL_GetRectIntersection(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result)
SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
Definition SDL_rect.h:159
SDL_bool SDL_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result)
SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon)
Definition SDL_rect.h:364
SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r)
Definition SDL_rect.h:311
#define SDL_TRUE
Definition SDL_stdinc.h:160
#define SDL_FALSE
Definition SDL_stdinc.h:151
int SDL_bool
Definition SDL_stdinc.h:170
#define SDL_FLT_EPSILON
Definition SDL_stdinc.h:268
float SDL_fabsf(float x)
float x
Definition SDL_rect.h:64
float y
Definition SDL_rect.h:65
float h
Definition SDL_rect.h:110
float x
Definition SDL_rect.h:107
float w
Definition SDL_rect.h:109
float y
Definition SDL_rect.h:108
int h
Definition SDL_rect.h:85
int w
Definition SDL_rect.h:85
int y
Definition SDL_rect.h:84
int x
Definition SDL_rect.h:84