From fdc04708f1950ad76eff16fd47ffe67dcdc5ba04 Mon Sep 17 00:00:00 2001 From: SDL Wiki Bot 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 bdb37f73d5..360ee95513 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 4b08b0b112..2ff52dc1df 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 73a7d368e2..8078a0c88f 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