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 (integer)
42 *
43 * \sa SDL_GetRectEnclosingPoints
44 * \sa SDL_PointInRect
45 */
46typedef struct SDL_Point
47{
48 int x;
49 int y;
50} SDL_Point;
51
52/**
53 * The structure that defines a point (floating point)
54 *
55 * \sa SDL_GetRectEnclosingPointsFloat
56 * \sa SDL_PointInRectFloat
57 */
58typedef struct SDL_FPoint
59{
60 float x;
61 float y;
63
64
65/**
66 * A rectangle, with the origin at the upper left (integer).
67 *
68 * \sa SDL_RectEmpty
69 * \sa SDL_RectsEqual
70 * \sa SDL_HasRectIntersection
71 * \sa SDL_GetRectIntersection
72 * \sa SDL_GetRectAndLineIntersection
73 * \sa SDL_GetRectUnion
74 * \sa SDL_GetRectEnclosingPoints
75 */
76typedef struct SDL_Rect
77{
78 int x, y;
79 int w, h;
80} SDL_Rect;
81
82
83/**
84 * A rectangle, with the origin at the upper left (floating point).
85 *
86 * \sa SDL_RectEmptyFloat
87 * \sa SDL_RectsEqualFloat
88 * \sa SDL_RectsEqualEpsilon
89 * \sa SDL_HasRectIntersectionFloat
90 * \sa SDL_GetRectIntersectionFloat
91 * \sa SDL_GetRectAndLineIntersectionFloat
92 * \sa SDL_GetRectUnionFloat
93 * \sa SDL_GetRectEnclosingPointsFloat
94 * \sa SDL_PointInRectFloat
95 */
96typedef struct SDL_FRect
97{
98 float x;
99 float y;
100 float w;
101 float h;
102} SDL_FRect;
103
104
105/**
106 * Returns true if point resides inside a rectangle.
107 */
109{
110 return ( (p->x >= r->x) && (p->x < (r->x + r->w)) &&
111 (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE;
112}
113
114/**
115 * Returns true if the rectangle has no area.
116 */
118{
119 return ((!r) || (r->w <= 0) || (r->h <= 0)) ? SDL_TRUE : SDL_FALSE;
120}
121
122/**
123 * Returns true if the two rectangles are equal.
124 */
126{
127 return (a && b && (a->x == b->x) && (a->y == b->y) &&
128 (a->w == b->w) && (a->h == b->h)) ? SDL_TRUE : SDL_FALSE;
129}
130
131/**
132 * Determine whether two rectangles intersect.
133 *
134 * If either pointer is NULL the function will return SDL_FALSE.
135 *
136 * \param A an SDL_Rect structure representing the first rectangle
137 * \param B an SDL_Rect structure representing the second rectangle
138 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
139 *
140 * \since This function is available since SDL 3.0.0.
141 *
142 * \sa SDL_GetRectIntersection
143 */
144extern DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(const SDL_Rect * A,
145 const SDL_Rect * B);
146
147/**
148 * Calculate the intersection of two rectangles.
149 *
150 * If `result` is NULL then this function will return SDL_FALSE.
151 *
152 * \param A an SDL_Rect structure representing the first rectangle
153 * \param B an SDL_Rect structure representing the second rectangle
154 * \param result an SDL_Rect structure filled in with the intersection of
155 * rectangles `A` and `B`
156 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
157 *
158 * \since This function is available since SDL 3.0.0.
159 *
160 * \sa SDL_HasRectIntersection
161 */
162extern DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersection(const SDL_Rect * A,
163 const SDL_Rect * B,
164 SDL_Rect * result);
165
166/**
167 * Calculate the union of two rectangles.
168 *
169 * \param A an SDL_Rect structure representing the first rectangle
170 * \param B an SDL_Rect structure representing the second rectangle
171 * \param result an SDL_Rect structure filled in with the union of rectangles
172 * `A` and `B`
173 * \returns 0 on success or a negative error code on failure; call
174 * SDL_GetError() for more information.
175 *
176 * \since This function is available since SDL 3.0.0.
177 */
178extern DECLSPEC int SDLCALL SDL_GetRectUnion(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 3.0.0.
198 */
199extern DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPoints(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 3.0.0.
221 */
222extern DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(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 */
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 * \since This function is available since SDL 3.0.0.
243 */
245{
246 return ((!r) || (r->w <= 0.0f) || (r->h <= 0.0f)) ? SDL_TRUE : SDL_FALSE;
247}
248
249/**
250 * Returns true if the two rectangles are equal, within some given epsilon.
251 *
252 * \since This function is available since SDL 3.0.0.
253 */
254SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon)
255{
256 return (a && b && ((a == b) ||
257 ((SDL_fabsf(a->x - b->x) <= epsilon) &&
258 (SDL_fabsf(a->y - b->y) <= epsilon) &&
259 (SDL_fabsf(a->w - b->w) <= epsilon) &&
260 (SDL_fabsf(a->h - b->h) <= epsilon))))
262}
263
264/**
265 * Returns true if the two rectangles are equal, using a default epsilon.
266 *
267 * \since This function is available since SDL 3.0.0.
268 */
273
274/**
275 * Determine whether two rectangles intersect with float precision.
276 *
277 * If either pointer is NULL the function will return SDL_FALSE.
278 *
279 * \param A an SDL_FRect structure representing the first rectangle
280 * \param B an SDL_FRect structure representing the second rectangle
281 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
282 *
283 * \since This function is available since SDL 3.0.0.
284 *
285 * \sa SDL_GetRectIntersection
286 */
287extern DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect * A,
288 const SDL_FRect * B);
289
290/**
291 * Calculate the intersection of two rectangles with float precision.
292 *
293 * If `result` is NULL then this function will return SDL_FALSE.
294 *
295 * \param A an SDL_FRect structure representing the first rectangle
296 * \param B an SDL_FRect structure representing the second rectangle
297 * \param result an SDL_FRect structure filled in with the intersection of
298 * rectangles `A` and `B`
299 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
300 *
301 * \since This function is available since SDL 3.0.0.
302 *
303 * \sa SDL_HasRectIntersectionFloat
304 */
305extern DECLSPEC SDL_bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect * A,
306 const SDL_FRect * B,
307 SDL_FRect * result);
308
309/**
310 * Calculate the union of two rectangles with float precision.
311 *
312 * \param A an SDL_FRect structure representing the first rectangle
313 * \param B an SDL_FRect structure representing the second rectangle
314 * \param result an SDL_FRect structure filled in with the union of rectangles
315 * `A` and `B`
316 * \returns 0 on success or a negative error code on failure; call
317 * SDL_GetError() for more information.
318 *
319 * \since This function is available since SDL 3.0.0.
320 */
321extern DECLSPEC int SDLCALL SDL_GetRectUnionFloat(const SDL_FRect * A,
322 const SDL_FRect * B,
323 SDL_FRect * result);
324
325/**
326 * Calculate a minimal rectangle enclosing a set of points with float
327 * precision.
328 *
329 * If `clip` is not NULL then only points inside of the clipping rectangle are
330 * considered.
331 *
332 * \param points an array of SDL_FPoint structures representing points to be
333 * enclosed
334 * \param count the number of structures in the `points` array
335 * \param clip an SDL_FRect used for clipping or NULL to enclose all points
336 * \param result an SDL_FRect structure filled in with the minimal enclosing
337 * rectangle
338 * \returns SDL_TRUE if any points were enclosed or SDL_FALSE if all the
339 * points were outside of the clipping rectangle.
340 *
341 * \since This function is available since SDL 3.0.0.
342 */
343extern DECLSPEC SDL_bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoint * points,
344 int count,
345 const SDL_FRect * clip,
346 SDL_FRect * result);
347
348/**
349 * Calculate the intersection of a rectangle and line segment with float
350 * precision.
351 *
352 * This function is used to clip a line segment to a rectangle. A line segment
353 * contained entirely within the rectangle or that does not intersect will
354 * remain unchanged. A line segment that crosses the rectangle at either or
355 * both ends will be clipped to the boundary of the rectangle and the new
356 * coordinates saved in `X1`, `Y1`, `X2`, and/or `Y2` as necessary.
357 *
358 * \param rect an SDL_FRect structure representing the rectangle to intersect
359 * \param X1 a pointer to the starting X-coordinate of the line
360 * \param Y1 a pointer to the starting Y-coordinate of the line
361 * \param X2 a pointer to the ending X-coordinate of the line
362 * \param Y2 a pointer to the ending Y-coordinate of the line
363 * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
364 *
365 * \since This function is available since SDL 3.0.0.
366 */
368 rect, float *X1,
369 float *Y1, float *X2,
370 float *Y2);
371
372/* Ends C function definitions when using C++ */
373#ifdef __cplusplus
374}
375#endif
376#include <SDL3/SDL_close_code.h>
377
378#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:108
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:244
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:269
SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b)
Definition SDL_rect.h:125
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:117
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:254
SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r)
Definition SDL_rect.h:233
#define SDL_TRUE
Definition SDL_stdinc.h:136
#define SDL_FALSE
Definition SDL_stdinc.h:135
int SDL_bool
Definition SDL_stdinc.h:137
#define SDL_FLT_EPSILON
Definition SDL_stdinc.h:209
float SDL_fabsf(float x)
float x
Definition SDL_rect.h:60
float y
Definition SDL_rect.h:61
float h
Definition SDL_rect.h:101
float x
Definition SDL_rect.h:98
float w
Definition SDL_rect.h:100
float y
Definition SDL_rect.h:99
int h
Definition SDL_rect.h:79
int w
Definition SDL_rect.h:79
int y
Definition SDL_rect.h:78
int x
Definition SDL_rect.h:78