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#include <SDL3/SDL_pixels.h>
34#include <SDL3/SDL_rwops.h>
35
36#include <SDL3/SDL_begin_code.h>
37/* Set up for C function definitions, even when using C++ */
38#ifdef __cplusplus
39extern "C" {
40#endif
41
42/**
43 * The structure that defines a point (integer)
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 (floating point)
56 *
57 * \sa SDL_GetRectEnclosingPointsFloat
58 * \sa SDL_PointInRectFloat
59 */
60typedef struct SDL_FPoint
61{
62 float x;
63 float y;
65
66
67/**
68 * A rectangle, with the origin at the upper left (integer).
69 *
70 * \sa SDL_RectEmpty
71 * \sa SDL_RectsEqual
72 * \sa SDL_HasRectIntersection
73 * \sa SDL_GetRectIntersection
74 * \sa SDL_GetRectAndLineIntersection
75 * \sa SDL_GetRectUnion
76 * \sa SDL_GetRectEnclosingPoints
77 */
78typedef 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_RectEmptyFloat
89 * \sa SDL_RectsEqualFloat
90 * \sa SDL_RectsEqualEpsilon
91 * \sa SDL_HasRectIntersectionFloat
92 * \sa SDL_GetRectIntersectionFloat
93 * \sa SDL_GetRectAndLineIntersectionFloat
94 * \sa SDL_GetRectUnionFloat
95 * \sa SDL_GetRectEnclosingPointsFloat
96 * \sa SDL_PointInRectFloat
97 */
98typedef 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 */
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 */
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 */
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 3.0.0.
143 *
144 * \sa SDL_GetRectIntersection
145 */
146extern DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(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 3.0.0.
161 *
162 * \sa SDL_HasRectIntersection
163 */
164extern DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(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 * \returns 0 on success or a negative error code on failure; call
176 * SDL_GetError() for more information.
177 *
178 * \since This function is available since SDL 3.0.0.
179 */
180extern DECLSPEC int SDLCALL SDL_GetRectUnion(const SDL_Rect * A,
181 const SDL_Rect * B,
182 SDL_Rect * result);
183
184/**
185 * Calculate a minimal rectangle enclosing a set of points.
186 *
187 * If `clip` is not NULL then only points inside of the clipping rectangle are
188 * considered.
189 *
190 * \param points an array of SDL_Point structures representing points to be
191 * enclosed
192 * \param count the number of structures in the `points` array
193 * \param clip an SDL_Rect used for clipping or NULL to enclose all points
194 * \param result an SDL_Rect structure filled in with the minimal enclosing
195 * rectangle
196 * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
197 * points were outside of the clipping rectangle.
198 *
199 * \since This function is available since SDL 3.0.0.
200 */
201extern DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point * points,
202 int count,
203 const SDL_Rect * clip,
204 SDL_Rect * result);
205
206/**
207 * Calculate the intersection of a rectangle and line segment.
208 *
209 * This function is used to clip a line segment to a rectangle. A line segment
210 * contained entirely within the rectangle or that does not intersect will
211 * remain unchanged. A line segment that crosses the rectangle at either or
212 * both ends will be clipped to the boundary of the rectangle and the new
213 * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
214 *
215 * \param rect an SDL_Rect structure representing the rectangle to intersect
216 * \param X1 a pointer to the starting X-coordinate of the line
217 * \param Y1 a pointer to the starting Y-coordinate of the line
218 * \param X2 a pointer to the ending X-coordinate of the line
219 * \param Y2 a pointer to the ending Y-coordinate of the line
220 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
221 *
222 * \since This function is available since SDL 3.0.0.
223 */
224extern DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *
225 rect, int *X1,
226 int *Y1, int *X2,
227 int *Y2);
228
229
230/* SDL_FRect versions... */
231
232/**
233 * Returns true if point resides inside a rectangle.
234 */
236{
237 return ( (p->x >= r->x) && (p->x < (r->x + r->w)) &&
238 (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE;
239}
240
241/**
242 * Returns true if the rectangle has no area.
243 *
244 * \since This function is available since SDL 3.0.0.
245 */
247{
248 return ((!r) || (r->w <= 0.0f) || (r->h <= 0.0f)) ? SDL_TRUE : SDL_FALSE;
249}
250
251/**
252 * Returns true if the two rectangles are equal, within some given epsilon.
253 *
254 * \since This function is available since SDL 3.0.0.
255 */
256SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon)
257{
258 return (a && b && ((a == b) ||
259 ((SDL_fabsf(a->x - b->x) <= epsilon) &&
260 (SDL_fabsf(a->y - b->y) <= epsilon) &&
261 (SDL_fabsf(a->w - b->w) <= epsilon) &&
262 (SDL_fabsf(a->h - b->h) <= epsilon))))
264}
265
266/**
267 * Returns true if the two rectangles are equal, using a default epsilon.
268 *
269 * \since This function is available since SDL 3.0.0.
270 */
275
276/**
277 * Determine whether two rectangles intersect with float precision.
278 *
279 * If either pointer is NULL the function will return SDL_FALSE.
280 *
281 * \param A an SDL_FRect structure representing the first rectangle
282 * \param B an SDL_FRect structure representing the second rectangle
283 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
284 *
285 * \since This function is available since SDL 3.0.0.
286 *
287 * \sa SDL_GetRectIntersection
288 */
289extern DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect * A,
290 const SDL_FRect * B);
291
292/**
293 * Calculate the intersection of two rectangles with float precision.
294 *
295 * If `result` is NULL then this function will return SDL_FALSE.
296 *
297 * \param A an SDL_FRect structure representing the first rectangle
298 * \param B an SDL_FRect structure representing the second rectangle
299 * \param result an SDL_FRect structure filled in with the intersection of
300 * rectangles `A` and `B`
301 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
302 *
303 * \since This function is available since SDL 3.0.0.
304 *
305 * \sa SDL_HasRectIntersectionFloat
306 */
307extern DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect * A,
308 const SDL_FRect * B,
309 SDL_FRect * result);
310
311/**
312 * Calculate the union of two rectangles with float precision.
313 *
314 * \param A an SDL_FRect structure representing the first rectangle
315 * \param B an SDL_FRect structure representing the second rectangle
316 * \param result an SDL_FRect structure filled in with the union of rectangles
317 * `A` and `B`
318 * \returns 0 on success or a negative error code on failure; call
319 * SDL_GetError() for more information.
320 *
321 * \since This function is available since SDL 3.0.0.
322 */
323extern DECLSPEC int SDLCALL SDL_GetRectUnionFloat(const SDL_FRect * A,
324 const SDL_FRect * B,
325 SDL_FRect * result);
326
327/**
328 * Calculate a minimal rectangle enclosing a set of points with float
329 * precision.
330 *
331 * If `clip` is not NULL then only points inside of the clipping rectangle are
332 * considered.
333 *
334 * \param points an array of SDL_FPoint structures representing points to be
335 * enclosed
336 * \param count the number of structures in the `points` array
337 * \param clip an SDL_FRect used for clipping or NULL to enclose all points
338 * \param result an SDL_FRect structure filled in with the minimal enclosing
339 * rectangle
340 * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
341 * points were outside of the clipping rectangle.
342 *
343 * \since This function is available since SDL 3.0.0.
344 */
345extern DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint * points,
346 int count,
347 const SDL_FRect * clip,
348 SDL_FRect * result);
349
350/**
351 * Calculate the intersection of a rectangle and line segment with float
352 * precision.
353 *
354 * This function is used to clip a line segment to a rectangle. A line segment
355 * contained entirely within the rectangle or that does not intersect will
356 * remain unchanged. A line segment that crosses the rectangle at either or
357 * both ends will be clipped to the boundary of the rectangle and the new
358 * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
359 *
360 * \param rect an SDL_FRect structure representing the rectangle to intersect
361 * \param X1 a pointer to the starting X-coordinate of the line
362 * \param Y1 a pointer to the starting Y-coordinate of the line
363 * \param X2 a pointer to the ending X-coordinate of the line
364 * \param Y2 a pointer to the ending Y-coordinate of the line
365 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
366 *
367 * \since This function is available since SDL 3.0.0.
368 */
370 rect, float *X1,
371 float *Y1, float *X2,
372 float *Y2);
373
374/* Ends C function definitions when using C++ */
375#ifdef __cplusplus
376}
377#endif
378#include <SDL3/SDL_close_code.h>
379
380#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:110
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:246
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:271
SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b)
Definition SDL_rect.h:127
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:119
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:256
SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r)
Definition SDL_rect.h:235
#define SDL_TRUE
Definition SDL_stdinc.h:135
#define SDL_FALSE
Definition SDL_stdinc.h:134
int SDL_bool
Definition SDL_stdinc.h:136
#define SDL_FLT_EPSILON
Definition SDL_stdinc.h:198
float SDL_fabsf(float x)
float x
Definition SDL_rect.h:62
float y
Definition SDL_rect.h:63
float h
Definition SDL_rect.h:103
float x
Definition SDL_rect.h:100
float w
Definition SDL_rect.h:102
float y
Definition SDL_rect.h:101
int h
Definition SDL_rect.h:81
int w
Definition SDL_rect.h:81
int y
Definition SDL_rect.h:80
int x
Definition SDL_rect.h:80