ruby2d 0.10.0 → 0.11.2

data/assets/include/SDL2/SDL_pixels.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -301,6 +301,11 @@ typedef enum
         SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ')
 } SDL_PixelFormatEnum;
 
+/**
+ * The bits of this structure can be directly reinterpreted as an integer-packed
+ * color which uses the SDL_PIXELFORMAT_RGBA32 format (SDL_PIXELFORMAT_ABGR8888
+ * on little-endian systems and SDL_PIXELFORMAT_RGBA8888 on big-endian systems).
+ */
 typedef struct SDL_Color
 {
     Uint8 r;
@@ -345,16 +350,31 @@ typedef struct SDL_PixelFormat
 } SDL_PixelFormat;
 
 /**
- * \brief Get the human readable name of a pixel format
+ * Get the human readable name of a pixel format.
+ *
+ * \param format the pixel format to query
+ * \returns the human readable name of the specified pixel format or
+ *          `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format);
 
 /**
- *  \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
+ * Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
+ *
+ * \param format one of the SDL_PixelFormatEnum values
+ * \param bpp a bits per pixel value; usually 15, 16, or 32
+ * \param Rmask a pointer filled in with the red mask for the format
+ * \param Gmask a pointer filled in with the green mask for the format
+ * \param Bmask a pointer filled in with the blue mask for the format
+ * \param Amask a pointer filled in with the alpha mask for the format
+ * \returns SDL_TRUE on success or SDL_FALSE if the conversion wasn't
+ *          possible; call SDL_GetError() for more information.
  *
- *  \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_MasksToPixelFormatEnum()
+ * \sa SDL_MasksToPixelFormatEnum
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
                                                             int *bpp,
@@ -364,12 +384,21 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
                                                             Uint32 * Amask);
 
 /**
- *  \brief Convert a bpp and RGBA masks to an enumerated pixel format.
+ * Convert a bpp value and RGBA masks to an enumerated pixel format.
+ *
+ * This will return `SDL_PIXELFORMAT_UNKNOWN` if the conversion wasn't
+ * possible.
  *
- *  \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion
- *          wasn't possible.
+ * \param bpp a bits per pixel value; usually 15, 16, or 32
+ * \param Rmask the red mask for the format
+ * \param Gmask the green mask for the format
+ * \param Bmask the blue mask for the format
+ * \param Amask the alpha mask for the format
+ * \returns one of the SDL_PixelFormatEnum values
  *
- *  \sa SDL_PixelFormatEnumToMasks()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_PixelFormatEnumToMasks
  */
 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
                                                           Uint32 Rmask,
@@ -378,84 +407,213 @@ extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
                                                           Uint32 Amask);
 
 /**
- *  \brief Create an SDL_PixelFormat structure from a pixel format enum.
+ * Create an SDL_PixelFormat structure corresponding to a pixel format.
+ *
+ * Returned structure may come from a shared global cache (i.e. not newly
+ * allocated), and hence should not be modified, especially the palette. Weird
+ * errors such as `Blit combination not supported` may occur.
+ *
+ * \param pixel_format one of the SDL_PixelFormatEnum values
+ * \returns the new SDL_PixelFormat structure or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_FreeFormat
  */
 extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format);
 
 /**
- *  \brief Free an SDL_PixelFormat structure.
+ * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat().
+ *
+ * \param format the SDL_PixelFormat structure to free
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AllocFormat
  */
 extern DECLSPEC void SDLCALL SDL_FreeFormat(SDL_PixelFormat *format);
 
 /**
- *  \brief Create a palette structure with the specified number of color
- *         entries.
+ * Create a palette structure with the specified number of color entries.
  *
- *  \return A new palette, or NULL if there wasn't enough memory.
+ * The palette entries are initialized to white.
  *
- *  \note The palette entries are initialized to white.
+ * \param ncolors represents the number of color entries in the color palette
+ * \returns a new SDL_Palette structure on success or NULL on failure (e.g. if
+ *          there wasn't enough memory); call SDL_GetError() for more
+ *          information.
  *
- *  \sa SDL_FreePalette()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_FreePalette
  */
 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
 
 /**
- *  \brief Set the palette for a pixel format structure.
+ * Set the palette for a pixel format structure.
+ *
+ * \param format the SDL_PixelFormat structure that will use the palette
+ * \param palette the SDL_Palette structure that will be used
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AllocPalette
+ * \sa SDL_FreePalette
  */
 extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
                                                       SDL_Palette *palette);
 
 /**
- *  \brief Set a range of colors in a palette.
+ * Set a range of colors in a palette.
+ *
+ * \param palette the SDL_Palette structure to modify
+ * \param colors an array of SDL_Color structures to copy into the palette
+ * \param firstcolor the index of the first palette entry to modify
+ * \param ncolors the number of entries to modify
+ * \returns 0 on success or a negative error code if not all of the colors
+ *          could be set; call SDL_GetError() for more information.
  *
- *  \param palette    The palette to modify.
- *  \param colors     An array of colors to copy into the palette.
- *  \param firstcolor The index of the first palette entry to modify.
- *  \param ncolors    The number of entries to modify.
+ * \since This function is available since SDL 2.0.0.
  *
- *  \return 0 on success, or -1 if not all of the colors could be set.
+ * \sa SDL_AllocPalette
+ * \sa SDL_CreateRGBSurface
  */
 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
                                                  const SDL_Color * colors,
                                                  int firstcolor, int ncolors);
 
 /**
- *  \brief Free a palette created with SDL_AllocPalette().
+ * Free a palette created with SDL_AllocPalette().
+ *
+ * \param palette the SDL_Palette structure to be freed
  *
- *  \sa SDL_AllocPalette()
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_AllocPalette
  */
 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
 
 /**
- *  \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
+ * Map an RGB triple to an opaque pixel value for a given pixel format.
+ *
+ * This function maps the RGB color value to the specified pixel format and
+ * returns the pixel value best approximating the given RGB color value for
+ * the given pixel format.
  *
- *  \sa SDL_MapRGBA
+ * If the format has a palette (8-bit) the index of the closest matching color
+ * in the palette will be returned.
+ *
+ * If the specified pixel format has an alpha component it will be returned as
+ * all 1 bits (fully opaque).
+ *
+ * If the pixel format bpp (color depth) is less than 32-bpp then the unused
+ * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
+ * format the return value can be assigned to a Uint16, and similarly a Uint8
+ * for an 8-bpp format).
+ *
+ * \param format an SDL_PixelFormat structure describing the pixel format
+ * \param r the red component of the pixel in the range 0-255
+ * \param g the green component of the pixel in the range 0-255
+ * \param b the blue component of the pixel in the range 0-255
+ * \returns a pixel value
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetRGB
+ * \sa SDL_GetRGBA
+ * \sa SDL_MapRGBA
  */
 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
                                           Uint8 r, Uint8 g, Uint8 b);
 
 /**
- *  \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
+ * Map an RGBA quadruple to a pixel value for a given pixel format.
+ *
+ * This function maps the RGBA color value to the specified pixel format and
+ * returns the pixel value best approximating the given RGBA color value for
+ * the given pixel format.
+ *
+ * If the specified pixel format has no alpha component the alpha value will
+ * be ignored (as it will be in formats with a palette).
+ *
+ * If the format has a palette (8-bit) the index of the closest matching color
+ * in the palette will be returned.
+ *
+ * If the pixel format bpp (color depth) is less than 32-bpp then the unused
+ * upper bits of the return value can safely be ignored (e.g., with a 16-bpp
+ * format the return value can be assigned to a Uint16, and similarly a Uint8
+ * for an 8-bpp format).
+ *
+ * \param format an SDL_PixelFormat structure describing the format of the
+ *               pixel
+ * \param r the red component of the pixel in the range 0-255
+ * \param g the green component of the pixel in the range 0-255
+ * \param b the blue component of the pixel in the range 0-255
+ * \param a the alpha component of the pixel in the range 0-255
+ * \returns a pixel value
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  \sa SDL_MapRGB
+ * \sa SDL_GetRGB
+ * \sa SDL_GetRGBA
+ * \sa SDL_MapRGB
  */
 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
                                            Uint8 r, Uint8 g, Uint8 b,
                                            Uint8 a);
 
 /**
- *  \brief Get the RGB components from a pixel of the specified format.
+ * Get RGB values from a pixel in the specified format.
  *
- *  \sa SDL_GetRGBA
+ * This function uses the entire 8-bit [0..255] range when converting color
+ * components from pixel formats with less than 8-bits per RGB component
+ * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
+ * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
+ *
+ * \param pixel a pixel value
+ * \param format an SDL_PixelFormat structure describing the format of the
+ *               pixel
+ * \param r a pointer filled in with the red component
+ * \param g a pointer filled in with the green component
+ * \param b a pointer filled in with the blue component
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetRGBA
+ * \sa SDL_MapRGB
+ * \sa SDL_MapRGBA
  */
 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
                                         const SDL_PixelFormat * format,
                                         Uint8 * r, Uint8 * g, Uint8 * b);
 
 /**
- *  \brief Get the RGBA components from a pixel of the specified format.
+ * Get RGBA values from a pixel in the specified format.
+ *
+ * This function uses the entire 8-bit [0..255] range when converting color
+ * components from pixel formats with less than 8-bits per RGB component
+ * (e.g., a completely white pixel in 16-bit RGB565 format would return [0xff,
+ * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
+ *
+ * If the surface has no alpha component, the alpha will be returned as 0xff
+ * (100% opaque).
  *
- *  \sa SDL_GetRGB
+ * \param pixel a pixel value
+ * \param format an SDL_PixelFormat structure describing the format of the
+ *               pixel
+ * \param r a pointer filled in with the red component
+ * \param g a pointer filled in with the green component
+ * \param b a pointer filled in with the blue component
+ * \param a a pointer filled in with the alpha component
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_GetRGB
+ * \sa SDL_MapRGB
+ * \sa SDL_MapRGBA
  */
 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
                                          const SDL_PixelFormat * format,
@@ -463,7 +621,14 @@ extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
                                          Uint8 * a);
 
 /**
- *  \brief Calculate a 256 entry gamma ramp for a gamma value.
+ * Calculate a 256 entry gamma ramp for a gamma value.
+ *
+ * \param gamma a gamma value where 0.0 is black and 1.0 is identity
+ * \param ramp an array of 256 values filled in with the gamma ramp
+ *
+ * \since This function is available since SDL 2.0.0.
+ *
+ * \sa SDL_SetWindowGammaRamp
  */
 extern DECLSPEC void SDLCALL SDL_CalculateGammaRamp(float gamma, Uint16 * ramp);
 

data/assets/include/SDL2/SDL_platform.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -70,6 +70,27 @@
 /* lets us know what version of Mac OS X we're compiling on */
 #include "AvailabilityMacros.h"
 #include "TargetConditionals.h"
+
+/* Fix building with older SDKs that don't define these
+   See this for more information:
+   https://stackoverflow.com/questions/12132933/preprocessor-macro-for-os-x-targets
+*/
+#ifndef TARGET_OS_MACCATALYST
+#define TARGET_OS_MACCATALYST 0
+#endif
+#ifndef TARGET_OS_IOS
+#define TARGET_OS_IOS 0
+#endif
+#ifndef TARGET_OS_IPHONE
+#define TARGET_OS_IPHONE 0
+#endif
+#ifndef TARGET_OS_TV
+#define TARGET_OS_TV 0
+#endif
+#ifndef TARGET_OS_SIMULATOR
+#define TARGET_OS_SIMULATOR 0
+#endif
+
 #if TARGET_OS_TV
 #undef __TVOS__
 #define __TVOS__ 1
@@ -175,6 +196,9 @@
 #define __SDL_NOGETPROCADDR__
 #endif
 
+#if defined(__vita__)
+#define __VITA__ 1
+#endif
 
 #include "begin_code.h"
 /* Set up for C function definitions, even when using C++ */
@@ -183,7 +207,20 @@ extern "C" {
 #endif
 
 /**
- *  \brief Gets the name of the platform.
+ * Get the name of the platform.
+ *
+ * Here are the names returned for some (but not all) supported platforms:
+ *
+ * - "Windows"
+ * - "Mac OS X"
+ * - "Linux"
+ * - "iOS"
+ * - "Android"
+ *
+ * \returns the name of the platform. If the correct platform name is not
+ *          available, returns a string beginning with the text "Unknown".
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC const char * SDLCALL SDL_GetPlatform (void);
 

data/assets/include/SDL2/SDL_power.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -37,7 +37,7 @@ extern "C" {
 #endif
 
 /**
- *  \brief The basic state for the system's power supply.
+ *  The basic state for the system's power supply.
  */
 typedef enum
 {
@@ -50,17 +50,30 @@ typedef enum
 
 
 /**
- *  \brief Get the current power supply details.
+ * Get the current power supply details.
  *
- *  \param secs Seconds of battery life left. You can pass a NULL here if
- *              you don't care. Will return -1 if we can't determine a
- *              value, or we're not running on a battery.
+ * You should never take a battery status as absolute truth. Batteries
+ * (especially failing batteries) are delicate hardware, and the values
+ * reported here are best estimates based on what that hardware reports. It's
+ * not uncommon for older batteries to lose stored power much faster than it
+ * reports, or completely drain when reporting it has 20 percent left, etc.
  *
- *  \param pct Percentage of battery life left, between 0 and 100. You can
- *             pass a NULL here if you don't care. Will return -1 if we
- *             can't determine a value, or we're not running on a battery.
+ * Battery status can change at any time; if you are concerned with power
+ * state, you should call this function frequently, and perhaps ignore changes
+ * until they seem to be stable for a few seconds.
  *
- *  \return The state of the battery (if any).
+ * It's possible a platform can only report battery percentage or time left
+ * but not both.
+ *
+ * \param secs seconds of battery life left, you can pass a NULL here if you
+ *             don't care, will return -1 if we can't determine a value, or
+ *             we're not running on a battery
+ * \param pct percentage of battery life left, between 0 and 100, you can pass
+ *            a NULL here if you don't care, will return -1 if we can't
+ *            determine a value, or we're not running on a battery
+ * \returns an SDL_PowerState enum representing the current battery state.
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *secs, int *pct);
 

data/assets/include/SDL2/SDL_quit.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages

data/assets/include/SDL2/SDL_rect.h

@@ -1,6 +1,6 @@
 /*
   Simple DirectMedia Layer
-  Copyright (C) 1997-2020 Sam Lantinga <slouken@libsdl.org>
+  Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
 
   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
@@ -40,10 +40,10 @@ extern "C" {
 #endif
 
 /**
- *  \brief  The structure that defines a point (integer)
+ * The structure that defines a point (integer)
  *
- *  \sa SDL_EnclosePoints
- *  \sa SDL_PointInRect
+ * \sa SDL_EnclosePoints
+ * \sa SDL_PointInRect
  */
 typedef struct SDL_Point
 {
@@ -52,10 +52,10 @@ typedef struct SDL_Point
 } SDL_Point;
 
 /**
- *  \brief  The structure that defines a point (floating point)
+ * The structure that defines a point (floating point)
  *
- *  \sa SDL_EnclosePoints
- *  \sa SDL_PointInRect
+ * \sa SDL_EnclosePoints
+ * \sa SDL_PointInRect
  */
 typedef struct SDL_FPoint
 {
@@ -65,14 +65,14 @@ typedef struct SDL_FPoint
 
 
 /**
- *  \brief A rectangle, with the origin at the upper left (integer).
- *
- *  \sa SDL_RectEmpty
- *  \sa SDL_RectEquals
- *  \sa SDL_HasIntersection
- *  \sa SDL_IntersectRect
- *  \sa SDL_UnionRect
- *  \sa SDL_EnclosePoints
+ * A rectangle, with the origin at the upper left (integer).
+ *
+ * \sa SDL_RectEmpty
+ * \sa SDL_RectEquals
+ * \sa SDL_HasIntersection
+ * \sa SDL_IntersectRect
+ * \sa SDL_UnionRect
+ * \sa SDL_EnclosePoints
  */
 typedef struct SDL_Rect
 {
@@ -82,7 +82,7 @@ typedef struct SDL_Rect
 
 
 /**
- *  \brief A rectangle, with the origin at the upper left (floating point).
+ * A rectangle, with the origin at the upper left (floating point).
  */
 typedef struct SDL_FRect
 {
@@ -94,7 +94,7 @@ typedef struct SDL_FRect
 
 
 /**
- *  \brief Returns true if point resides inside a rectangle.
+ * Returns true if point resides inside a rectangle.
  */
 SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
 {
@@ -103,7 +103,7 @@ SDL_FORCE_INLINE SDL_bool SDL_PointInRect(const SDL_Point *p, const SDL_Rect *r)
 }
 
 /**
- *  \brief Returns true if the rectangle has no area.
+ * Returns true if the rectangle has no area.
  */
 SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
 {
@@ -111,7 +111,7 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEmpty(const SDL_Rect *r)
 }
 
 /**
- *  \brief Returns true if the two rectangles are equal.
+ * Returns true if the two rectangles are equal.
  */
 SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
 {
@@ -120,33 +120,70 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEquals(const SDL_Rect *a, const SDL_Rect *b)
 }
 
 /**
- *  \brief Determine whether two rectangles intersect.
+ * Determine whether two rectangles intersect.
+ *
+ * If either pointer is NULL the function will return SDL_FALSE.
+ *
+ * \param A an SDL_Rect structure representing the first rectangle
+ * \param B an SDL_Rect structure representing the second rectangle
+ * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ *
+ * \since This function is available since SDL 2.0.0.
  *
- *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ * \sa SDL_IntersectRect
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A,
                                                      const SDL_Rect * B);
 
 /**
- *  \brief Calculate the intersection of two rectangles.
+ * Calculate the intersection of two rectangles.
+ *
+ * If `result` is NULL then this function will return SDL_FALSE.
+ *
+ * \param A an SDL_Rect structure representing the first rectangle
+ * \param B an SDL_Rect structure representing the second rectangle
+ * \param result an 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 2.0.0.
  *
- *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ * \sa SDL_HasIntersection
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A,
                                                    const SDL_Rect * B,
                                                    SDL_Rect * result);
 
 /**
- *  \brief Calculate the union of two rectangles.
+ * Calculate the union of two rectangles.
+ *
+ * \param A an SDL_Rect structure representing the first rectangle
+ * \param B an SDL_Rect structure representing the second rectangle
+ * \param result an SDL_Rect structure filled in with the union of rectangles
+ *               `A` and `B`
+ *
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A,
                                            const SDL_Rect * B,
                                            SDL_Rect * result);
 
 /**
- *  \brief Calculate a minimal rectangle enclosing a set of points
+ * Calculate a minimal rectangle enclosing a set of points.
+ *
+ * If `clip` is not NULL then only points inside of the clipping rectangle are
+ * considered.
  *
- *  \return SDL_TRUE if any points were within the clipping rect
+ * \param points an array of SDL_Point structures representing points to be
+ *               enclosed
+ * \param count the number of structures in the `points` array
+ * \param clip an SDL_Rect used for clipping or NULL to enclose all points
+ * \param result an 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 2.0.0.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points,
                                                    int count,
@@ -154,9 +191,22 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points,
                                                    SDL_Rect * result);
 
 /**
- *  \brief Calculate the intersection of a rectangle and line segment.
+ * 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.
+ *
+ * \param rect an SDL_Rect structure representing the rectangle to intersect
+ * \param X1 a pointer to the starting X-coordinate of the line
+ * \param Y1 a pointer to the starting Y-coordinate of the line
+ * \param X2 a pointer to the ending X-coordinate of the line
+ * \param Y2 a pointer to the ending Y-coordinate of the line
+ * \returns SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
  *
- *  \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise.
+ * \since This function is available since SDL 2.0.0.
  */
 extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRectAndLine(const SDL_Rect *
                                                           rect, int *X1,