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 "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(x: a->x - b->x) <= epsilon) && |
256 | (SDL_fabsf(x: a->y - b->y) <= epsilon) && |
257 | (SDL_fabsf(x: a->w - b->w) <= epsilon) && |
258 | (SDL_fabsf(x: 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: */ |
377 | |