eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-05-29 07:59:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

include: Updated a bunch of documentation.

Browse source
This commit is contained in:
Ryan C. Gordon 2024-04-13 20:10:13 -04:00
parent 3c86af5901
commit 081a94e321
No known key found for this signature in database
GPG key ID: FA148B892AB48044
3 changed files with 327 additions and 121 deletions
Download patch file Download diff file Expand all files Collapse all files

139
include/SDL3/SDL_rect.h
View file

@ -112,16 +112,49 @@ typedef struct SDL_FRect
/**
* Returns true if point resides inside a rectangle.
* 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).
*
* \param p the point to test.
* \param r the 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.
*/
SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
{
return ( (p->x >= r->x) && (p->x < (r->x + r->w)) &&
return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) &&
(p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE;
}
/**
* Returns true if the rectangle has no area.
* 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).
*
* \param r the 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.
*/
SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
{
@ -129,7 +162,23 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
}
/**
* Returns true if the two rectangles are equal.
* 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).
*
* \param a the first rectangle to test.
* \param b the 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.
*/
SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b)
{
@ -146,12 +195,14 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqual(const SDL_Rect *a, const SDL_Rect *b)
* \param B an 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.
*
* \sa SDL_GetRectIntersection
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasRectIntersection(const SDL_Rect * A,
const SDL_Rect * B);
const SDL_Rect * B);
/**
* Calculate the intersection of two rectangles.
@ -237,16 +288,47 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetRectAndLineIntersection(const SDL_Rect *
/* SDL_FRect versions... */
/**
* Returns true if point resides inside a rectangle.
* 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) 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).
*
* \param p the point to test.
* \param r the 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.
*/
SDL_FORCE_INLINE SDL_bool SDL_PointInRectFloat(const SDL_FPoint *p, const SDL_FRect *r)
{
return ( (p->x >= r->x) && (p->x < (r->x + r->w)) &&
return ( p && r && (p->x >= r->x) && (p->x < (r->x + r->w)) &&
(p->y >= r->y) && (p->y < (r->y + r->h)) ) ? SDL_TRUE : SDL_FALSE;
}
/**
* Returns true if the rectangle has no area.
* Determine whether a floating point 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.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).
*
* \param r the 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.
*/
@ -256,9 +338,27 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmptyFloat(const SDL_FRect *r)
}
/**
* Returns true if the two rectangles are equal, within some given 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).
*
* \param a the first rectangle to test.
* \param b the 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.
*
* \sa SDL_RectsEqualFloat
*/
SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FRect *b, const float epsilon)
{
@ -271,9 +371,28 @@ SDL_FORCE_INLINE SDL_bool SDL_RectsEqualEpsilon(const SDL_FRect *a, const SDL_FR
}
/**
* Returns true if the two rectangles are equal, using a default epsilon.
* 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).
*
* \param a the first rectangle to test.
* \param b the 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.
*
* \sa SDL_RectsEqualEpsilon
*/
SDL_FORCE_INLINE SDL_bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b)
{