From 23311884679c479c6679df1dc9e8941fd43474a0 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Thu, 23 Oct 2025 14:54:47 +0000
Subject: [PATCH] Sync SDL3 wiki -> header
[ci skip]
---
include/SDL3/SDL_surface.h | 126 ++++++++++++++++++++++++-------------
1 file changed, 83 insertions(+), 43 deletions(-)
diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index 5ec439deeee1a..34ecafb2d02ea 100644
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -29,12 +29,16 @@
* provides a reasonable toolbox for transforming the data, including copying
* between surfaces, filling rectangles in the image data, etc.
*
- * There is also a simple .bmp loader, SDL_LoadBMP(), and a simple .png loader, SDL_LoadPNG(). SDL itself does not
- * provide loaders for other file formats, but there are several
- * excellent external libraries that do, including its own satellite library,
- * [SDL_image](https://wiki.libsdl.org/SDL3_image).
+ * There is also a simple .bmp loader, SDL_LoadBMP(), and a simple .png
+ * loader, SDL_LoadPNG(). SDL itself does not provide loaders for other file
+ * formats, but there are several excellent external libraries that do,
+ * including its own satellite library,
+ * [SDL_image](https://wiki.libsdl.org/SDL3_image)
+ * .
*
- * In general these functions are thread-safe in that they can be called on different threads with different surfaces. You should not try to modify any surface from two threads simultaneously.
+ * In general these functions are thread-safe in that they can be called on
+ * different threads with different surfaces. You should not try to modify any
+ * surface from two threads simultaneously.
*/
#ifndef SDL_surface_h_
@@ -266,7 +270,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surfac
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -285,7 +290,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface,
* \returns the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if
* the surface is NULL.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -315,7 +321,8 @@ extern SDL_DECLSPEC SDL_Colorspace SDLCALL SDL_GetSurfaceColorspace(SDL_Surface
* the surface didn't have an index format); call SDL_GetError() for
* more information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -336,7 +343,8 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_CreateSurfacePalette(SDL_Surface *
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -377,7 +385,8 @@ extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetSurfacePalette(SDL_Surface *sur
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -420,7 +429,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasAlternateImages(SDL_Surface *surf
* failure; call SDL_GetError() for more information. This should be
* freed with SDL_free() when it is no longer needed.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -438,7 +448,8 @@ extern SDL_DECLSPEC SDL_Surface ** SDLCALL SDL_GetSurfaceImages(SDL_Surface *sur
*
* \param surface the SDL_Surface structure to update.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -464,9 +475,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveSurfaceAlternateImages(SDL_Surface *s
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces. The locking referred to by
- * this function is making the pixels available for direct
- * access, not thread-safe locking.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces. The locking referred to by this function
+ * is making the pixels available for direct access, not
+ * thread-safe locking.
*
* \since This function is available since SDL 3.2.0.
*
@@ -548,7 +560,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP(const char *file);
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -571,7 +584,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SaveBMP_IO(SDL_Surface *surface, SDL_IOStre
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -632,7 +646,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_LoadPNG(const char *file);
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.4.0.
*
@@ -649,7 +664,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SavePNG_IO(SDL_Surface *surface, SDL_IOStre
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.4.0.
*
@@ -669,7 +685,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SavePNG(SDL_Surface *surface, const char *f
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -711,7 +728,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface);
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -776,7 +794,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorKey(SDL_Surface *surface, Ui
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -796,7 +815,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceColorMod(SDL_Surface *surface, Ui
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -818,7 +838,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceColorMod(SDL_Surface *surface, Ui
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -856,7 +877,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface *surface, Ui
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -895,7 +917,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface *surface, S
* \returns true if the rectangle intersects the surface, otherwise false and
* blits will be completely clipped.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -916,7 +939,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface, co
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -932,7 +956,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface, SD
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*/
@@ -952,7 +977,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipM
* \returns a rotated copy of the surface or NULL on failure; call
* SDL_GetError() for more information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.4.0.
*/
@@ -970,7 +996,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_RotateSurface(SDL_Surface *surface
* \returns a copy of the surface or NULL on failure; call SDL_GetError() for
* more information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -991,7 +1018,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_DuplicateSurface(SDL_Surface *surf
* \returns a copy of the surface or NULL on failure; call SDL_GetError() for
* more information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -1018,7 +1046,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ScaleSurface(SDL_Surface *surface,
* \returns the new SDL_Surface structure that is created or NULL on failure;
* call SDL_GetError() for more information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -1046,7 +1075,8 @@ extern SDL_DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface(SDL_Surface *surfac
* \returns the new SDL_Surface structure that is created or NULL on failure;
* call SDL_GetError() for more information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -1149,7 +1179,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*/
@@ -1171,7 +1202,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PremultiplySurfaceAlpha(SDL_Surface *surfac
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*/
@@ -1196,7 +1228,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ClearSurface(SDL_Surface *surface, float r,
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -1223,7 +1256,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_FillSurfaceRect(SDL_Surface *dst, const SDL
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -1514,7 +1548,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_BlitSurface9Grid(SDL_Surface *src, const SD
* \param b the blue component of the pixel in the range 0-255.
* \returns a pixel value.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -1547,7 +1582,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGB(SDL_Surface *surface, Uint8
* \param a the alpha component of the pixel in the range 0-255.
* \returns a pixel value.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*
@@ -1578,7 +1614,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGBA(SDL_Surface *surface, Uint
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*/
@@ -1604,7 +1641,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixel(SDL_Surface *surface, int
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*/
@@ -1629,7 +1667,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadSurfacePixelFloat(SDL_Surface *surface,
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*/
@@ -1651,7 +1690,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WriteSurfacePixel(SDL_Surface *surface, int
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
- * \threadsafety This function can be called on different threads with different surfaces.
+ * \threadsafety This function can be called on different threads with
+ * different surfaces.
*
* \since This function is available since SDL 3.2.0.
*/