mirror of
https://github.com/libsdl-org/SDL.git
synced 2025-05-28 15:39:10 +00:00
include: Updated a bunch of documentation.
This commit is contained in:
parent
3c86af5901
commit
081a94e321
3 changed files with 327 additions and 121 deletions
|
@ -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)
|
||||
{
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue