SDL: Sync SDL3 wiki -> header (fdc04)

From fdc04708f1950ad76eff16fd47ffe67dcdc5ba04 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Wed, 10 Jul 2024 07:48:48 +0000
Subject: [PATCH] Sync SDL3 wiki -> header

---
 include/SDL3/SDL_pixels.h  | 38 ++++++++++++++++++++++++--------------
 include/SDL3/SDL_render.h  |  3 ++-
 include/SDL3/SDL_surface.h | 30 ++++++++++++++++++------------
 3 files changed, 44 insertions(+), 27 deletions(-)

diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h
index bdb37f73d5a66..360ee955133eb 100644
--- a/include/SDL3/SDL_pixels.h
+++ b/include/SDL3/SDL_pixels.h
@@ -803,8 +803,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat forma
  * \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 the SDL_PixelFormat value corresponding to the format masks,
- *          or SDL_PIXELFORMAT_UNKNOWN if there isn't a match.
+ * \returns the SDL_PixelFormat value corresponding to the format masks, or
+ *          SDL_PIXELFORMAT_UNKNOWN if there isn't a match.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -822,8 +822,8 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatForMasks(int bpp,
  * errors such as `Blit combination not supported` may occur.
  *
  * \param format one of the SDL_PixelFormat values.
- * \returns a pointer to a SDL_PixelFormatDetails structure or NULL on failure; call
- *          SDL_GetError() for more information.
+ * \returns a pointer to a SDL_PixelFormatDetails structure or NULL on
+ *          failure; call SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -861,7 +861,8 @@ extern SDL_DECLSPEC SDL_Palette *SDLCALL SDL_CreatePalette(int ncolors);
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
- * \threadsafety It is safe to call this function from any thread, as long as the palette is not modified or destroyed in another thread.
+ * \threadsafety It is safe to call this function from any thread, as long as
+ *               the palette is not modified or destroyed in another thread.
  *
  * \since This function is available since SDL 3.0.0.
  */
@@ -872,7 +873,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const
  *
  * \param palette the SDL_Palette structure to be freed.
  *
- * \threadsafety It is safe to call this function from any thread, as long as the palette is not modified or destroyed in another thread.
+ * \threadsafety It is safe to call this function from any thread, as long as
+ *               the palette is not modified or destroyed in another thread.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -898,14 +900,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette *palette);
  * format the return value can be assigned to a Uint16, and similarly a Uint8
  * for an 8-bpp format).
  *
- * \param format a pointer to SDL_PixelFormatDetails describing the pixel format.
+ * \param format a pointer to SDL_PixelFormatDetails describing the pixel
+ *               format.
  * \param palette an optional palette for indexed formats, may be NULL.
  * \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.
  *
- * \threadsafety It is safe to call this function from any thread, as long as the palette is not modified.
+ * \threadsafety It is safe to call this function from any thread, as long as
+ *               the palette is not modified.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -933,7 +937,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *form
  * format the return value can be assigned to a Uint16, and similarly a Uint8
  * for an 8-bpp format).
  *
- * \param format a pointer to SDL_PixelFormatDetails describing the pixel format.
+ * \param format a pointer to SDL_PixelFormatDetails describing the pixel
+ *               format.
  * \param palette an optional palette for indexed formats, may be NULL.
  * \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.
@@ -941,7 +946,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *form
  * \param a the alpha component of the pixel in the range 0-255.
  * \returns a pixel value.
  *
- * \threadsafety It is safe to call this function from any thread, as long as the palette is not modified.
+ * \threadsafety It is safe to call this function from any thread, as long as
+ *               the palette is not modified.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -960,13 +966,15 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormatDetails *for
  * 0xff, 0xff] not [0xf8, 0xfc, 0xf8]).
  *
  * \param pixel a pixel value.
- * \param format a pointer to SDL_PixelFormatDetails describing the pixel format.
+ * \param format a pointer to SDL_PixelFormatDetails describing the pixel
+ *               format.
  * \param palette an optional palette for indexed formats, may be NULL.
  * \param r a pointer filled in with the red component, may be NULL.
  * \param g a pointer filled in with the green component, may be NULL.
  * \param b a pointer filled in with the blue component, may be NULL.
  *
- * \threadsafety It is safe to call this function from any thread, as long as the palette is not modified.
+ * \threadsafety It is safe to call this function from any thread, as long as
+ *               the palette is not modified.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -988,14 +996,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, const SDL_PixelFormatD
  * (100% opaque).
  *
  * \param pixel a pixel value.
- * \param format a pointer to SDL_PixelFormatDetails describing the pixel format.
+ * \param format a pointer to SDL_PixelFormatDetails describing the pixel
+ *               format.
  * \param palette an optional palette for indexed formats, may be NULL.
  * \param r a pointer filled in with the red component, may be NULL.
  * \param g a pointer filled in with the green component, may be NULL.
  * \param b a pointer filled in with the blue component, may be NULL.
  * \param a a pointer filled in with the alpha component, may be NULL.
  *
- * \threadsafety It is safe to call this function from any thread, as long as the palette is not modified.
+ * \threadsafety It is safe to call this function from any thread, as long as
+ *               the palette is not modified.
  *
  * \since This function is available since SDL 3.0.0.
  *
diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h
index 4b08b0b11264e..2ff52dc1dffd5 100644
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@@ -350,7 +350,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetRendererName(SDL_Renderer *render
  * - `SDL_PROP_RENDERER_VSYNC_NUMBER`: the current vsync setting
  * - `SDL_PROP_RENDERER_MAX_TEXTURE_SIZE_NUMBER`: the maximum texture width
  *   and height
- * - `SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER`: a (const SDL_PixelFormat *) array of pixel formats, terminated with SDL_PIXELFORMAT_UNKNOWN,
+ * - `SDL_PROP_RENDERER_TEXTURE_FORMATS_POINTER`: a (const SDL_PixelFormat *)
+ *   array of pixel formats, terminated with SDL_PIXELFORMAT_UNKNOWN,
  *   representing the available texture formats for this renderer.
  * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace value
  *   describing the colorspace for output to the display, defaults to
diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index 73a7d368e2d7c..8078a0c88f03c 100644
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -139,7 +139,8 @@ typedef struct SDL_Surface
 extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurface(int width, int height, SDL_PixelFormat format);
 
 /**
- * Allocate a new surface with a specific pixel format and existing pixel data.
+ * Allocate a new surface with a specific pixel format and existing pixel
+ * data.
  *
  * No copy is made of the pixel data. Pixel data is not managed automatically;
  * you must free the surface before you free the pixel data.
@@ -247,7 +248,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, S
  * other RGB surfaces and SDL_COLORSPACE_BT709_FULL for YUV textures.
  *
  * \param surface the SDL_Surface structure to query.
- * \returns the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if the surface is NULL.
+ * \returns the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if
+ *          the surface is NULL.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -276,7 +278,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_
  * Get the palette used by a surface.
  *
  * \param surface the SDL_Surface structure to query.
- * \returns a pointer to the palette used by the surface, or NULL if there is no palette used.
+ * \returns a pointer to the palette used by the surface, or NULL if there is
+ *          no palette used.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -407,7 +410,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *fi
  * the surface must be locked before directly accessing the pixels.
  *
  * \param surface the SDL_Surface structure to optimize.
- * \param enabled SDL_TRUE to enable RLE acceleration, SDL_FALSE to disable it.
+ * \param enabled SDL_TRUE to enable RLE acceleration, SDL_FALSE to disable
+ *                it.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
@@ -444,7 +448,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface);
  * SDL_MapRGB().
  *
  * \param surface the SDL_Surface structure to update.
- * \param enabled SDL_TRUE to enable color key, SDL_FALSE to disable color key.
+ * \param enabled SDL_TRUE to enable color key, SDL_FALSE to disable color
+ *                key.
  * \param key the transparent pixel.
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
@@ -675,7 +680,8 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface *surfa
  * surface. The new, optimized surface can then be used as the source for
  * future blits, making them faster.
  *
- * If you are converting to an indexed surface and want to map colors to a palette, you can use SDL_ConvertSurfaceAndColorspace() instead.
+ * If you are converting to an indexed surface and want to map colors to a
+ * palette, you can use SDL_ConvertSurfaceAndColorspace() instead.
  *
  * \param surface the existing SDL_Surface structure to convert.
  * \param format the new pixel format.
@@ -1013,8 +1019,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src,
  * returns the pixel value best approximating the given RGB color value for
  * the given pixel format.
  *
- * If the surface has a palette, the index of the closest matching color
- * in the palette will be returned.
+ * If the surface has a palette, the index of the closest matching color in
+ * the palette will be returned.
  *
  * If the surface pixel format has an alpha component it will be returned as
  * all 1 bits (fully opaque).
@@ -1043,11 +1049,11 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGB(SDL_Surface *surface, Uint8
  * returns the pixel value best approximating the given RGBA color value for
  * the given pixel format.
  *
- * If the surface pixel format has no alpha component the alpha value will
- * be ignored (as it will be in formats with a palette).
+ * If the surface pixel format has no alpha component the alpha value will be
+ * ignored (as it will be in formats with a palette).
  *
- * If the surface has a palette, the index of the closest matching color
- * in the palette will be returned.
+ * If the surface has a palette, 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