diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h index 5ec439deee..34ecafb2d0 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. */