SDL 3.0
SDL_rect.h File Reference
+ Include dependency graph for SDL_rect.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  SDL_Point
 
struct  SDL_FPoint
 
struct  SDL_Rect
 
struct  SDL_FRect
 

Functions

SDL_FORCE_INLINE SDL_bool SDL_PointInRect (const SDL_Point *p, const SDL_Rect *r)
 
SDL_FORCE_INLINE SDL_bool SDL_RectEmpty (const SDL_Rect *r)
 
SDL_FORCE_INLINE SDL_bool SDL_RectsEqual (const SDL_Rect *a, const SDL_Rect *b)
 
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)
 
int SDL_GetRectUnion (const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result)
 
SDL_bool SDL_GetRectEnclosingPoints (const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result)
 
SDL_bool SDL_GetRectAndLineIntersection (const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2)
 
SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat (const SDL_FPoint *p, const SDL_FRect *r)
 
SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat (const SDL_FRect *r)
 
SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon (const SDL_FRect *a, const SDL_FRect *b, const float epsilon)
 
SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat (const SDL_FRect *a, const SDL_FRect *b)
 
SDL_bool SDL_HasRectIntersectionFloat (const SDL_FRect *A, const SDL_FRect *B)
 
SDL_bool SDL_GetRectIntersectionFloat (const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result)
 
int SDL_GetRectUnionFloat (const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result)
 
SDL_bool SDL_GetRectEnclosingPointsFloat (const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result)
 
SDL_bool SDL_GetRectAndLineIntersectionFloat (const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2)
 

Function Documentation

◆ SDL_GetRectAndLineIntersection()

SDL_bool SDL_GetRectAndLineIntersection ( const SDL_Rect rect,
int *  X1,
int *  Y1,
int *  X2,
int *  Y2 
)
extern

Calculate the intersection of a rectangle and line segment.

This function is used to clip a line segment to a rectangle. A line segment contained entirely within the rectangle or that does not intersect will remain unchanged. A line segment that crosses the rectangle at either or both ends will be clipped to the boundary of the rectangle and the new coordinates saved in X1, Y1, X2, and/or Y2 as necessary.

Parameters
rectan SDL_Rect structure representing the rectangle to intersect.
X1a pointer to the starting X-coordinate of the line.
Y1a pointer to the starting Y-coordinate of the line.
X2a pointer to the ending X-coordinate of the line.
Y2a pointer to the ending Y-coordinate of the line.
Returns
SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetRectAndLineIntersectionFloat()

SDL_bool SDL_GetRectAndLineIntersectionFloat ( const SDL_FRect rect,
float *  X1,
float *  Y1,
float *  X2,
float *  Y2 
)
extern

Calculate the intersection of a rectangle and line segment with float precision.

This function is used to clip a line segment to a rectangle. A line segment contained entirely within the rectangle or that does not intersect will remain unchanged. A line segment that crosses the rectangle at either or both ends will be clipped to the boundary of the rectangle and the new coordinates saved in X1, Y1, X2, and/or Y2 as necessary.

Parameters
rectan SDL_FRect structure representing the rectangle to intersect.
X1a pointer to the starting X-coordinate of the line.
Y1a pointer to the starting Y-coordinate of the line.
X2a pointer to the ending X-coordinate of the line.
Y2a pointer to the ending Y-coordinate of the line.
Returns
SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetRectEnclosingPoints()

SDL_bool SDL_GetRectEnclosingPoints ( const SDL_Point points,
int  count,
const SDL_Rect clip,
SDL_Rect result 
)
extern

Calculate a minimal rectangle enclosing a set of points.

If clip is not NULL then only points inside of the clipping rectangle are considered.

Parameters
pointsan array of SDL_Point structures representing points to be enclosed.
countthe number of structures in the points array.
clipan SDL_Rect used for clipping or NULL to enclose all points.
resultan SDL_Rect structure filled in with the minimal enclosing rectangle.
Returns
SDL_TRUE if any points were enclosed or SDL_FALSE if all the points were outside of the clipping rectangle.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetRectEnclosingPointsFloat()

SDL_bool SDL_GetRectEnclosingPointsFloat ( const SDL_FPoint points,
int  count,
const SDL_FRect clip,
SDL_FRect result 
)
extern

Calculate a minimal rectangle enclosing a set of points with float precision.

If clip is not NULL then only points inside of the clipping rectangle are considered.

Parameters
pointsan array of SDL_FPoint structures representing points to be enclosed.
countthe number of structures in the points array.
clipan SDL_FRect used for clipping or NULL to enclose all points.
resultan SDL_FRect structure filled in with the minimal enclosing rectangle.
Returns
SDL_TRUE if any points were enclosed or SDL_FALSE if all the points were outside of the clipping rectangle.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetRectIntersection()

SDL_bool SDL_GetRectIntersection ( const SDL_Rect A,
const SDL_Rect B,
SDL_Rect result 
)
extern

Calculate the intersection of two rectangles.

If result is NULL then this function will return SDL_FALSE.

Parameters
Aan SDL_Rect structure representing the first rectangle.
Ban SDL_Rect structure representing the second rectangle.
resultan SDL_Rect structure filled in with the intersection of rectangles A and B.
Returns
SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.
See also
SDL_HasRectIntersection

◆ SDL_GetRectIntersectionFloat()

SDL_bool SDL_GetRectIntersectionFloat ( const SDL_FRect A,
const SDL_FRect B,
SDL_FRect result 
)
extern

Calculate the intersection of two rectangles with float precision.

If result is NULL then this function will return SDL_FALSE.

Parameters
Aan SDL_FRect structure representing the first rectangle.
Ban SDL_FRect structure representing the second rectangle.
resultan SDL_FRect structure filled in with the intersection of rectangles A and B.
Returns
SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.
See also
SDL_HasRectIntersectionFloat

◆ SDL_GetRectUnion()

int SDL_GetRectUnion ( const SDL_Rect A,
const SDL_Rect B,
SDL_Rect result 
)
extern

Calculate the union of two rectangles.

Parameters
Aan SDL_Rect structure representing the first rectangle.
Ban SDL_Rect structure representing the second rectangle.
resultan SDL_Rect structure filled in with the union of rectangles A and B.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_GetRectUnionFloat()

int SDL_GetRectUnionFloat ( const SDL_FRect A,
const SDL_FRect B,
SDL_FRect result 
)
extern

Calculate the union of two rectangles with float precision.

Parameters
Aan SDL_FRect structure representing the first rectangle.
Ban SDL_FRect structure representing the second rectangle.
resultan SDL_FRect structure filled in with the union of rectangles A and B.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.0.0.

◆ SDL_HasRectIntersection()

SDL_bool SDL_HasRectIntersection ( const SDL_Rect A,
const SDL_Rect B 
)
extern

Determine whether two rectangles intersect.

If either pointer is NULL the function will return SDL_FALSE.

Parameters
Aan SDL_Rect structure representing the first rectangle.
Ban SDL_Rect structure representing the second rectangle.
Returns
SDL_TRUE if there is an intersection, SDL_FALSE otherwise.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_GetRectIntersection

◆ SDL_HasRectIntersectionFloat()

SDL_bool SDL_HasRectIntersectionFloat ( const SDL_FRect A,
const SDL_FRect B 
)
extern

Determine whether two rectangles intersect with float precision.

If either pointer is NULL the function will return SDL_FALSE.

Parameters
Aan SDL_FRect structure representing the first rectangle.
Ban SDL_FRect structure representing the second rectangle.
Returns
SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
Since
This function is available since SDL 3.0.0.
See also
SDL_GetRectIntersection

◆ SDL_PointInRect()

SDL_FORCE_INLINE SDL_bool SDL_PointInRect ( const SDL_Point p,
const SDL_Rect r 
)

Determine whether a point resides inside a rectangle.

A point is considered part of a rectangle if both p and r are not NULL, and p's x and y coordinates are >= to the rectangle's top left corner, and < the rectangle's x+w and y+h. So a 1x1 rectangle considers point (0,0) as "inside" and (0,1) as not.

Note that this is a forced-inline function in a header, and not a public API function available in the SDL library (which is to say, the code is embedded in the calling program and the linker and dynamic loader will not be able to find this function inside SDL itself).

Parameters
pthe point to test.
rthe rectangle to test.
Returns
SDL_TRUE if p is contained by r, SDL_FALSE otherwise.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.

Definition at line 136 of file SDL_rect.h.

137{
138 return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) &&
139 (p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE;
140}
#define SDL_TRUE
Definition SDL_stdinc.h:203
#define SDL_FALSE
Definition SDL_stdinc.h:194
int h
Definition SDL_rect.h:86
int w
Definition SDL_rect.h:86
int y
Definition SDL_rect.h:85
int x
Definition SDL_rect.h:85

References SDL_Rect::h, SDL_FALSE, SDL_TRUE, SDL_Rect::w, SDL_Point::x, SDL_Rect::x, SDL_Point::y, and SDL_Rect::y.

◆ SDL_PointInRectFloat()

SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat ( const SDL_FPoint p,
const SDL_FRect r 
)

Determine whether a point resides inside a floating point rectangle.

A point is considered part of a rectangle if both p and r are not NULL, and p's x and y coordinates are >= to the rectangle's top left corner, and <= the rectangle's x+w and y+h. So a 1x1 rectangle considers point (0,0) and (0,1) as "inside" and (0,2) as not.

Note that this is a forced-inline function in a header, and not a public API function available in the SDL library (which is to say, the code is embedded in the calling program and the linker and dynamic loader will not be able to find this function inside SDL itself).

Parameters
pthe point to test.
rthe rectangle to test.
Returns
SDL_TRUE if p is contained by r, SDL_FALSE otherwise.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.

Definition at line 312 of file SDL_rect.h.

313{
314 return ( p && r && (p->x >= r->x) && (p->x <= (r->x + r->w)) &&
315 (p->y >= r->y) && (p->y <= (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE;
316}
float x
Definition SDL_rect.h:65
float y
Definition SDL_rect.h:66
float h
Definition SDL_rect.h:111
float x
Definition SDL_rect.h:108
float w
Definition SDL_rect.h:110
float y
Definition SDL_rect.h:109

References SDL_FRect::h, SDL_FALSE, SDL_TRUE, SDL_FRect::w, SDL_FPoint::x, SDL_FRect::x, SDL_FPoint::y, and SDL_FRect::y.

◆ SDL_RectEmpty()

SDL_FORCE_INLINE SDL_bool SDL_RectEmpty ( const SDL_Rect r)

Determine whether a rectangle has no area.

A rectangle is considered "empty" for this function if r is NULL, or if r's width and/or height are <= 0.

Note that this is a forced-inline function in a header, and not a public API function available in the SDL library (which is to say, the code is embedded in the calling program and the linker and dynamic loader will not be able to find this function inside SDL itself).

Parameters
rthe rectangle to test.
Returns
SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.

Definition at line 160 of file SDL_rect.h.

161{
162 return ((!r) || (r->w <= 0) || (r->h <= 0)) ? SDL_TRUE : SDL_FALSE;
163}

References SDL_Rect::h, SDL_FALSE, SDL_TRUE, and SDL_Rect::w.

◆ SDL_RectEmptyFloat()

SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat ( const SDL_FRect r)

Determine whether a floating point rectangle can contain any point.

A rectangle is considered "empty" for this function if r is NULL, or if r's width and/or height are < 0.0f.

Note that this is a forced-inline function in a header, and not a public API function available in the SDL library (which is to say, the code is embedded in the calling program and the linker and dynamic loader will not be able to find this function inside SDL itself).

Parameters
rthe rectangle to test.
Returns
SDL_TRUE if the rectangle is "empty", SDL_FALSE otherwise.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.

Definition at line 336 of file SDL_rect.h.

337{
338 return ((!r) || (r->w < 0.0f) || (r->h < 0.0f)) ? SDL_TRUE : SDL_FALSE;
339}

References SDL_FRect::h, SDL_FALSE, SDL_TRUE, and SDL_FRect::w.

◆ SDL_RectsEqual()

SDL_FORCE_INLINE SDL_bool SDL_RectsEqual ( const SDL_Rect a,
const SDL_Rect b 
)

Determine whether two rectangles are equal.

Rectangles are considered equal if both are not NULL and each of their x, y, width and height match.

Note that this is a forced-inline function in a header, and not a public API function available in the SDL library (which is to say, the code is embedded in the calling program and the linker and dynamic loader will not be able to find this function inside SDL itself).

Parameters
athe first rectangle to test.
bthe second rectangle to test.
Returns
SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.

Definition at line 184 of file SDL_rect.h.

185{
186 return (a && b && (a->x == b->x) && (a->y == b->y) &&
187 (a->w == b->w) && (a->h == b->h)) ? SDL_TRUE : SDL_FALSE;
188}

References SDL_Rect::h, SDL_FALSE, SDL_TRUE, SDL_Rect::w, SDL_Rect::x, and SDL_Rect::y.

◆ SDL_RectsEqualEpsilon()

SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon ( const SDL_FRect a,
const SDL_FRect b,
const float  epsilon 
)

Determine whether two floating point rectangles are equal, within some given epsilon.

Rectangles are considered equal if both are not NULL and each of their x, y, width and height are within epsilon of each other. If you don't know what value to use for epsilon, you should call the SDL_RectsEqualFloat function instead.

Note that this is a forced-inline function in a header, and not a public API function available in the SDL library (which is to say, the code is embedded in the calling program and the linker and dynamic loader will not be able to find this function inside SDL itself).

Parameters
athe first rectangle to test.
bthe second rectangle to test.
epsilonthe epsilon value for comparison.
Returns
SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_RectsEqualFloat

Definition at line 366 of file SDL_rect.h.

367{
368 return (a && b && ((a == b) ||
369 ((SDL_fabsf(a->x - b->x) <= epsilon) &&
370 (SDL_fabsf(a->y - b->y) <= epsilon) &&
371 (SDL_fabsf(a->w - b->w) <= epsilon) &&
372 (SDL_fabsf(a->h - b->h) <= epsilon))))
374}
float SDL_fabsf(float x)

References SDL_FRect::h, SDL_fabsf(), SDL_FALSE, SDL_TRUE, SDL_FRect::w, SDL_FRect::x, and SDL_FRect::y.

Referenced by SDL_RectsEqualFloat().

◆ SDL_RectsEqualFloat()

SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat ( const SDL_FRect a,
const SDL_FRect b 
)

Determine whether two floating point rectangles are equal, within a default epsilon.

Rectangles are considered equal if both are not NULL and each of their x, y, width and height are within SDL_FLT_EPSILON of each other. This is often a reasonable way to compare two floating point rectangles and deal with the slight precision variations in floating point calculations that tend to pop up.

Note that this is a forced-inline function in a header, and not a public API function available in the SDL library (which is to say, the code is embedded in the calling program and the linker and dynamic loader will not be able to find this function inside SDL itself).

Parameters
athe first rectangle to test.
bthe second rectangle to test.
Returns
SDL_TRUE if the rectangles are equal, SDL_FALSE otherwise.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.0.0.
See also
SDL_RectsEqualEpsilon

Definition at line 401 of file SDL_rect.h.

402{
404}
SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon)
Definition SDL_rect.h:366
#define SDL_FLT_EPSILON
Definition SDL_stdinc.h:327

References SDL_FLT_EPSILON, and SDL_RectsEqualEpsilon().