Simplified SDL_Surface

SDL_Surface has been simplified and internal details are no longer in the public structure. The `format` member of SDL_Surface is now an enumerated pixel format value. You can get the full details of the pixel format by calling `SDL_GetPixelFormatDetails(surface->format)`. You can get the palette associated with the surface by calling SDL_GetSurfacePalette(). You can get the clip rectangle by calling SDL_GetSurfaceClipRect(). SDL_PixelFormat has been renamed SDL_PixelFormatDetails and just describes the pixel format, it does not include a palette for indexed pixel types. SDL_PixelFormatEnum has been renamed SDL_PixelFormat and is used instead of Uint32 for API functions that refer to pixel format by enumerated value. SDL_MapRGB(), SDL_MapRGBA(), SDL_GetRGB(), and SDL_GetRGBA() take an optional palette parameter for indexed color lookups.
2025-09-27 21:48:29 +00:00 · 2024-07-08 14:59:18 -07:00
parent 40ed098ce8
commit 2ba76dbe80
123 changed files with 1865 additions and 1838 deletions
--- a/include/SDL3/SDL_camera.h
+++ b/include/SDL3/SDL_camera.h
@@ -78,7 +78,7 @@ typedef struct SDL_Camera SDL_Camera;
 */
 typedef struct SDL_CameraSpec
 {
-    SDL_PixelFormatEnum format; /**< Frame format */
+    SDL_PixelFormat format;     /**< Frame format */
    SDL_Colorspace colorspace;  /**< Frame colorspace */
    int width;                  /**< Frame width */
    int height;                 /**< Frame height */
--- a/include/SDL3/SDL_oldnames.h
+++ b/include/SDL3/SDL_oldnames.h
@@ -453,19 +453,18 @@
 #define SDL_sem SDL_Semaphore

 /* ##SDL_pixels.h */
-#define SDL_AllocFormat SDL_CreatePixelFormat
+#define SDL_AllocFormat SDL_GetPixelFormatDetails
 #define SDL_AllocPalette SDL_CreatePalette
 #define SDL_Colour SDL_Color
-#define SDL_FreeFormat SDL_DestroyPixelFormat
 #define SDL_FreePalette SDL_DestroyPalette
-#define SDL_MasksToPixelFormatEnum SDL_GetPixelFormatEnumForMasks
+#define SDL_MasksToPixelFormatEnum SDL_GetPixelFormatForMasks
 #define SDL_PIXELFORMAT_BGR444 SDL_PIXELFORMAT_XBGR4444
 #define SDL_PIXELFORMAT_BGR555 SDL_PIXELFORMAT_XBGR1555
 #define SDL_PIXELFORMAT_BGR888 SDL_PIXELFORMAT_XBGR8888
 #define SDL_PIXELFORMAT_RGB444 SDL_PIXELFORMAT_XRGB4444
 #define SDL_PIXELFORMAT_RGB555 SDL_PIXELFORMAT_XRGB1555
 #define SDL_PIXELFORMAT_RGB888 SDL_PIXELFORMAT_XRGB8888
-#define SDL_PixelFormatEnumToMasks SDL_GetMasksForPixelFormatEnum
+#define SDL_PixelFormatEnumToMasks SDL_GetMasksForPixelFormat

 /* ##SDL_rect.h */
 #define SDL_EncloseFPoints SDL_GetRectEnclosingPointsFloat
@@ -580,6 +579,7 @@

 /* ##SDL_surface.h */
 #define SDL_BlitScaled SDL_BlitSurfaceScaled
+#define SDL_ConvertSurfaceFormat SDL_ConvertSurface
 #define SDL_FillRect SDL_FillSurfaceRect
 #define SDL_FillRects SDL_FillSurfaceRects
 #define SDL_FreeSurface SDL_DestroySurface
@@ -590,6 +590,8 @@
 #define SDL_LoadBMP_RW SDL_LoadBMP_IO
 #define SDL_LowerBlit SDL_BlitSurfaceUnchecked
 #define SDL_LowerBlitScaled SDL_BlitSurfaceUncheckedScaled
+#define SDL_PREALLOC SDL_SURFACE_PREALLOCATED
+#define SDL_SIMD_ALIGNED SDL_SURFACE_SIMD_ALIGNED
 #define SDL_SaveBMP_RW SDL_SaveBMP_IO
 #define SDL_SetClipRect SDL_SetSurfaceClipRect
 #define SDL_SetColorKey SDL_SetSurfaceColorKey
@@ -1048,19 +1050,18 @@
 #define SDL_sem SDL_sem_renamed_SDL_Semaphore

 /* ##SDL_pixels.h */
-#define SDL_AllocFormat SDL_AllocFormat_renamed_SDL_CreatePixelFormat
+#define SDL_AllocFormat SDL_AllocFormat_renamed_SDL_GetPixelFormatDetails
 #define SDL_AllocPalette SDL_AllocPalette_renamed_SDL_CreatePalette
 #define SDL_Colour SDL_Colour_renamed_SDL_Color
-#define SDL_FreeFormat SDL_FreeFormat_renamed_SDL_DestroyPixelFormat
 #define SDL_FreePalette SDL_FreePalette_renamed_SDL_DestroyPalette
-#define SDL_MasksToPixelFormatEnum SDL_MasksToPixelFormatEnum_renamed_SDL_GetPixelFormatEnumForMasks
+#define SDL_MasksToPixelFormatEnum SDL_MasksToPixelFormatEnum_renamed_SDL_GetPixelFormatForMasks
 #define SDL_PIXELFORMAT_BGR444 SDL_PIXELFORMAT_BGR444_renamed_SDL_PIXELFORMAT_XBGR4444
 #define SDL_PIXELFORMAT_BGR555 SDL_PIXELFORMAT_BGR555_renamed_SDL_PIXELFORMAT_XBGR1555
 #define SDL_PIXELFORMAT_BGR888 SDL_PIXELFORMAT_BGR888_renamed_SDL_PIXELFORMAT_XBGR8888
 #define SDL_PIXELFORMAT_RGB444 SDL_PIXELFORMAT_RGB444_renamed_SDL_PIXELFORMAT_XRGB4444
 #define SDL_PIXELFORMAT_RGB555 SDL_PIXELFORMAT_RGB555_renamed_SDL_PIXELFORMAT_XRGB1555
 #define SDL_PIXELFORMAT_RGB888 SDL_PIXELFORMAT_RGB888_renamed_SDL_PIXELFORMAT_XRGB8888
-#define SDL_PixelFormatEnumToMasks SDL_PixelFormatEnumToMasks_renamed_SDL_GetMasksForPixelFormatEnum
+#define SDL_PixelFormatEnumToMasks SDL_PixelFormatEnumToMasks_renamed_SDL_GetMasksForPixelFormat

 /* ##SDL_rect.h */
 #define SDL_EncloseFPoints SDL_EncloseFPoints_renamed_SDL_GetRectEnclosingPointsFloat
@@ -1175,6 +1176,7 @@

 /* ##SDL_surface.h */
 #define SDL_BlitScaled SDL_BlitScaled_renamed_SDL_BlitSurfaceScaled
+#define SDL_ConvertSurfaceFormat SDL_ConvertSurfaceFormat_renamed_SDL_ConvertSurface
 #define SDL_FillRect SDL_FillRect_renamed_SDL_FillSurfaceRect
 #define SDL_FillRects SDL_FillRects_renamed_SDL_FillSurfaceRects
 #define SDL_FreeSurface SDL_FreeSurface_renamed_SDL_DestroySurface
@@ -1185,6 +1187,8 @@
 #define SDL_LoadBMP_RW SDL_LoadBMP_RW_renamed_SDL_LoadBMP_IO
 #define SDL_LowerBlit SDL_LowerBlit_renamed_SDL_BlitSurfaceUnchecked
 #define SDL_LowerBlitScaled SDL_LowerBlitScaled_renamed_SDL_BlitSurfaceUncheckedScaled
+#define SDL_PREALLOC SDL_PREALLOC_renamed_SDL_SURFACE_PREALLOCATED
+#define SDL_SIMD_ALIGNED SDL_SIMD_ALIGNED_renamed_SDL_SURFACE_SIMD_ALIGNED
 #define SDL_SaveBMP_RW SDL_SaveBMP_RW_renamed_SDL_SaveBMP_IO
 #define SDL_SetClipRect SDL_SetClipRect_renamed_SDL_SetSurfaceClipRect
 #define SDL_SetColorKey SDL_SetColorKey_renamed_SDL_SetSurfaceColorKey
--- a/include/SDL3/SDL_pixels.h
+++ b/include/SDL3/SDL_pixels.h
@@ -133,7 +133,8 @@ typedef enum SDL_PackedLayout
 #define SDL_PIXELTYPE(X)    (((X) >> 24) & 0x0F)
 #define SDL_PIXELORDER(X)   (((X) >> 20) & 0x0F)
 #define SDL_PIXELLAYOUT(X)  (((X) >> 16) & 0x0F)
-#define SDL_BITSPERPIXEL(X) (((X) >> 8) & 0xFF)
+#define SDL_BITSPERPIXEL(X) \
+    (SDL_ISPIXELFORMAT_FOURCC(X) ? 0 : (((X) >> 8) & 0xFF))
 #define SDL_BYTESPERPIXEL(X) \
    (SDL_ISPIXELFORMAT_FOURCC(X) ? \
        ((((X) == SDL_PIXELFORMAT_YUY2) || \
@@ -222,7 +223,7 @@ typedef enum SDL_PackedLayout
 *
 * \since This enum is available since SDL 3.0.0.
 */
-typedef enum SDL_PixelFormatEnum
+typedef enum SDL_PixelFormat
 {
    SDL_PIXELFORMAT_UNKNOWN,
    SDL_PIXELFORMAT_INDEX1LSB =
@@ -426,7 +427,7 @@ typedef enum SDL_PixelFormatEnum
        SDL_DEFINE_PIXELFOURCC('P', '0', '1', '0'),
    SDL_PIXELFORMAT_EXTERNAL_OES =      /**< Android video texture format */
        SDL_DEFINE_PIXELFOURCC('O', 'E', 'S', ' ')
-} SDL_PixelFormatEnum;
+} SDL_PixelFormat;

 /**
 * Pixels are a representation of a color in a particular color space.
@@ -721,7 +722,6 @@ typedef struct SDL_FColor
 *
 * \since This struct is available since SDL 3.0.0.
 *
- * \sa SDL_PixelFormat
 * \sa SDL_SetPaletteColors
 */
 typedef struct SDL_Palette
@@ -735,15 +735,11 @@ typedef struct SDL_Palette
 /**
 * Details about the format of a pixel.
 *
- * Generally this is used with SDL_Surface, and covers many possible
- * configurations, including paletted data and various bit patterns.
- *
 * \since This struct is available since SDL 3.0.0.
 */
-typedef struct SDL_PixelFormat
+typedef struct SDL_PixelFormatDetails
 {
-    SDL_PixelFormatEnum format;
-    SDL_Palette *palette;
+    SDL_PixelFormat format;
    Uint8 bits_per_pixel;
    Uint8 bytes_per_pixel;
    Uint8 padding[2];
@@ -751,17 +747,15 @@ typedef struct SDL_PixelFormat
    Uint32 Gmask;
    Uint32 Bmask;
    Uint32 Amask;
-    Uint8 Rloss;
-    Uint8 Gloss;
-    Uint8 Bloss;
-    Uint8 Aloss;
+    Uint8 Rbits;
+    Uint8 Gbits;
+    Uint8 Bbits;
+    Uint8 Abits;
    Uint8 Rshift;
    Uint8 Gshift;
    Uint8 Bshift;
    Uint8 Ashift;
-    int refcount;
-    struct SDL_PixelFormat *next;
-} SDL_PixelFormat;
+} SDL_PixelFormatDetails;

 /**
 * Get the human readable name of a pixel format.
@@ -772,32 +766,31 @@ typedef struct SDL_PixelFormat
 * \returns the human readable name of the specified pixel format or
 *          `SDL_PIXELFORMAT_UNKNOWN` if the format isn't recognized.
 *
+ * \threadsafety It is safe to call this function from any thread.
+ *
 * \since This function is available since SDL 3.0.0.
 */
-extern SDL_DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(SDL_PixelFormatEnum format);
+extern SDL_DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(SDL_PixelFormat format);

 /**
 * Convert one of the enumerated pixel formats to a bpp value and RGBA masks.
 *
- * \param format one of the SDL_PixelFormatEnum values.
+ * \param format one of the SDL_PixelFormat 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.
+ * \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.
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_GetPixelFormatEnumForMasks
+ * \sa SDL_GetPixelFormatForMasks
 */
-extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormatEnum(SDL_PixelFormatEnum format,
-                                                            int *bpp,
-                                                            Uint32 * Rmask,
-                                                            Uint32 * Gmask,
-                                                            Uint32 * Bmask,
-                                                            Uint32 * Amask);
+extern SDL_DECLSPEC int SDLCALL SDL_GetMasksForPixelFormat(SDL_PixelFormat format, int *bpp, Uint32 *Rmask, Uint32 *Gmask, Uint32 *Bmask, Uint32 *Amask);

 /**
 * Convert a bpp value and RGBA masks to an enumerated pixel format.
@@ -810,47 +803,33 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetMasksForPixelFormatEnum(SDL_PixelFor
 * \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_PixelFormatEnum value corresponding to the format masks,
+ * \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.
+ *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_GetMasksForPixelFormatEnum
+ * \sa SDL_GetMasksForPixelFormat
 */
-extern SDL_DECLSPEC SDL_PixelFormatEnum SDLCALL SDL_GetPixelFormatEnumForMasks(int bpp,
-                                                          Uint32 Rmask,
-                                                          Uint32 Gmask,
-                                                          Uint32 Bmask,
-                                                          Uint32 Amask);
+extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetPixelFormatForMasks(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);

 /**
- * Create an SDL_PixelFormat structure corresponding to a pixel format.
+ * Create an SDL_PixelFormatDetails 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
+ * \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.
 *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_DestroyPixelFormat
- * \sa SDL_SetPixelFormatPalette
- */
-extern SDL_DECLSPEC SDL_PixelFormat * SDLCALL SDL_CreatePixelFormat(SDL_PixelFormatEnum pixel_format);
-
-/**
- * Free an SDL_PixelFormat structure allocated by SDL_CreatePixelFormat().
- *
- * \param format the SDL_PixelFormat structure to free.
+ * \threadsafety It is safe to call this function from any thread.
 *
 * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_CreatePixelFormat
 */
-extern SDL_DECLSPEC void SDLCALL SDL_DestroyPixelFormat(SDL_PixelFormat *format);
+extern SDL_DECLSPEC const SDL_PixelFormatDetails * SDLCALL SDL_GetPixelFormatDetails(SDL_PixelFormat format);

 /**
 * Create a palette structure with the specified number of color entries.
@@ -862,27 +841,16 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyPixelFormat(SDL_PixelFormat *format)
 *          there wasn't enough memory); call SDL_GetError() for more
 *          information.
 *
+ * \threadsafety It is safe to call this function from any thread.
+ *
 * \since This function is available since SDL 3.0.0.
 *
 * \sa SDL_DestroyPalette
 * \sa SDL_SetPaletteColors
- * \sa SDL_SetPixelFormatPalette
+ * \sa SDL_SetSurfacePalette
 */
 extern SDL_DECLSPEC SDL_Palette *SDLCALL SDL_CreatePalette(int ncolors);

-/**
- * 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 3.0.0.
- */
-extern SDL_DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format,
-                                                      SDL_Palette *palette);
-
 /**
 * Set a range of colors in a palette.
 *
@@ -893,22 +861,24 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * form
 * \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.
+ *
 * \since This function is available since SDL 3.0.0.
 */
-extern SDL_DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
-                                                 const SDL_Color * colors,
-                                                 int firstcolor, int ncolors);
+extern SDL_DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Color *colors, int firstcolor, int ncolors);

 /**
 * Free a palette created with SDL_CreatePalette().
 *
 * \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.
+ *
 * \since This function is available since SDL 3.0.0.
 *
 * \sa SDL_CreatePalette
 */
-extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette * palette);
+extern SDL_DECLSPEC void SDLCALL SDL_DestroyPalette(SDL_Palette *palette);

 /**
 * Map an RGB triple to an opaque pixel value for a given pixel format.
@@ -928,20 +898,22 @@ 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 an SDL_PixelFormat structure 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.
+ *
 * \since This function is available since SDL 3.0.0.
 *
 * \sa SDL_GetRGB
- * \sa SDL_GetRGBA
 * \sa SDL_MapRGBA
+ * \sa SDL_MapSurfaceRGB
 */
-extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
-                                          Uint8 r, Uint8 g, Uint8 b);
+extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 r, Uint8 g, Uint8 b);

 /**
 * Map an RGBA quadruple to a pixel value for a given pixel format.
@@ -961,23 +933,23 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
 * 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 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.
 * \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.
+ *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_GetRGB
 * \sa SDL_GetRGBA
 * \sa SDL_MapRGB
+ * \sa SDL_MapSurfaceRGBA
 */
-extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
-                                           Uint8 r, Uint8 g, Uint8 b,
-                                           Uint8 a);
+extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 r, Uint8 g, Uint8 b, Uint8 a);

 /**
 * Get RGB values from a pixel in the specified format.
@@ -988,11 +960,13 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
 * 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.
+ * \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.
 *
 * \since This function is available since SDL 3.0.0.
 *
@@ -1000,9 +974,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
 * \sa SDL_MapRGB
 * \sa SDL_MapRGBA
 */
-extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
-                                        const SDL_PixelFormat * format,
-                                        Uint8 * r, Uint8 * g, Uint8 * b);
+extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 *r, Uint8 *g, Uint8 *b);

 /**
 * Get RGBA values from a pixel in the specified format.
@@ -1016,12 +988,14 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
 * (100% opaque).
 *
 * \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.
+ * \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.
 *
 * \since This function is available since SDL 3.0.0.
 *
@@ -1029,10 +1003,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
 * \sa SDL_MapRGB
 * \sa SDL_MapRGBA
 */
-extern SDL_DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
-                                         const SDL_PixelFormat * format,
-                                         Uint8 * r, Uint8 * g, Uint8 * b,
-                                         Uint8 * a);
+extern SDL_DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, const SDL_PixelFormatDetails *format, const SDL_Palette *palette, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);


 /* Ends C function definitions when using C++ */
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@@ -350,8 +350,7 @@ 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_PixelFormatEnum
- *   *) 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
@@ -485,7 +484,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *ren
 * Create a texture for a rendering context.
 *
 * \param renderer the rendering context.
- * \param format one of the enumerated values in SDL_PixelFormatEnum.
+ * \param format one of the enumerated values in SDL_PixelFormat.
 * \param access one of the enumerated values in SDL_TextureAccess.
 * \param w the width of the texture in pixels.
 * \param h the height of the texture in pixels.
@@ -501,7 +500,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *ren
 * \sa SDL_GetTextureSize
 * \sa SDL_UpdateTexture
 */
-extern SDL_DECLSPEC SDL_Texture *SDLCALL SDL_CreateTexture(SDL_Renderer *renderer, SDL_PixelFormatEnum format, int access, int w, int h);
+extern SDL_DECLSPEC SDL_Texture *SDLCALL SDL_CreateTexture(SDL_Renderer *renderer, SDL_PixelFormat format, int access, int w, int h);

 /**
 * Create a texture from an existing surface.
@@ -540,7 +539,7 @@ extern SDL_DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Render
 *   SDL_COLORSPACE_SRGB for other RGB textures and SDL_COLORSPACE_JPEG for
 *   YUV textures.
 * - `SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER`: one of the enumerated values in
- *   SDL_PixelFormatEnum, defaults to the best RGBA format for the renderer
+ *   SDL_PixelFormat, defaults to the best RGBA format for the renderer
 * - `SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER`: one of the enumerated values in
 *   SDL_TextureAccess, defaults to SDL_TEXTUREACCESS_STATIC
 * - `SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER`: the width of the texture in
@@ -672,7 +671,7 @@ extern SDL_DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureWithProperties(SDL_Ren
 * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_ColorSpace value describing
 *   the texture colorspace.
 * - `SDL_PROP_TEXTURE_FORMAT_NUMBER`: one of the enumerated values in
- *   SDL_PixelFormatEnum.
+ *   SDL_PixelFormat.
 * - `SDL_PROP_TEXTURE_ACCESS_NUMBER`: one of the enumerated values in
 *   SDL_TextureAccess.
 * - `SDL_PROP_TEXTURE_WIDTH_NUMBER`: the width of the texture in pixels.
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -45,34 +45,23 @@ extern "C" {
 /**
 * The flags on an SDL_Surface.
 *
- * These are generally meant to be considered read-only.
+ * These are generally considered read-only.
 *
 * \since This datatype is available since SDL 3.0.0.
 */
 typedef Uint32 SDL_SurfaceFlags;

-#define SDL_PREALLOC                0x00000001u /**< Surface uses preallocated memory */
-#define SDL_RLEACCEL                0x00000002u /**< Surface is RLE encoded */
-#define SDL_DONTFREE                0x00000004u /**< Surface is referenced internally */
-#define SDL_SIMD_ALIGNED            0x00000008u /**< Surface uses aligned memory */
-#define SDL_SURFACE_USES_PROPERTIES 0x00000010u /**< Surface uses properties */
+#define SDL_SURFACE_PREALLOCATED    0x00000001u /**< Surface uses preallocated pixel memory */
+#define SDL_SURFACE_LOCK_NEEDED     0x00000002u /**< Surface needs to be locked to access pixels */
+#define SDL_SURFACE_LOCKED          0x00000004u /**< Surface is currently locked */
+#define SDL_SURFACE_SIMD_ALIGNED    0x00000008u /**< Surface uses pixel memory allocated with SDL_aligned_alloc() */

 /**
 * Evaluates to true if the surface needs to be locked before access.
 *
 * \since This macro is available since SDL 3.0.0.
 */
-#define SDL_MUSTLOCK(S) (((S)->flags & SDL_RLEACCEL) != 0)
-
-/**
- * An opaque type used in SDL_Surface.
- *
- * This is used by SDL to keep track of how blit operations should work
- * internally; it is not for use directly by applications.
- *
- * \since This struct is available since SDL 3.0.0.
- */
-typedef struct SDL_BlitMap SDL_BlitMap;
+#define SDL_MUSTLOCK(S) (((S)->flags & (SDL_SURFACE_LOCK_NEEDED | SDL_SURFACE_LOCKED)) == SDL_SURFACE_LOCK_NEEDED)

 /**
 * The scaling mode.
@@ -98,6 +87,9 @@ typedef enum SDL_FlipMode
    SDL_FLIP_VERTICAL       /**< flip vertically */
 } SDL_FlipMode;

+/* Internal surface data */
+typedef struct SDL_SurfaceData SDL_SurfaceData;
+
 /**
 * A collection of pixels used in software blitting.
 *
@@ -118,36 +110,24 @@ typedef enum SDL_FlipMode
 typedef struct SDL_Surface
 {
    SDL_SurfaceFlags flags;     /**< Read-only */
-    SDL_PixelFormat *format;    /**< Read-only */
+    SDL_PixelFormat format;     /**< Read-only */
    int w, h;                   /**< Read-only */
    int pitch;                  /**< Read-only */
-    void *pixels;               /**< Read-write */
+    void *pixels;               /**< Read-only pointer, writable pixels if non-NULL */

-    void *reserved;             /**< Private */
+    int refcount;               /**< Application reference count, used when freeing surface */

-    /** information needed for surfaces requiring locks */
-    int locked;                 /**< Read-only */
+    SDL_SurfaceData *internal;  /**< Private */

-    /** list of BlitMap that hold a reference to this surface */
-    void *list_blitmap;         /**< Private */
-
-    /** clipping information */
-    SDL_Rect clip_rect;         /**< Read-only */
-
-    /** info for fast blit mapping to other surfaces */
-    SDL_BlitMap *map;           /**< Private */
-
-    /** Reference count -- used when freeing surface */
-    int refcount;               /**< Read-mostly */
 } SDL_Surface;


 /**
- * Allocate a new RGB surface with a specific pixel format.
+ * Allocate a new surface with a specific pixel format.
 *
 * \param width the width of the surface.
 * \param height the height of the surface.
- * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
+ * \param format the SDL_PixelFormat for the new surface's pixel format.
 * \returns the new SDL_Surface structure that is created or NULL if it fails;
 *          call SDL_GetError() for more information.
 *
@@ -156,11 +136,10 @@ typedef struct SDL_Surface
 * \sa SDL_CreateSurfaceFrom
 * \sa SDL_DestroySurface
 */
-extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurface(int width, int height, SDL_PixelFormatEnum format);
+extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurface(int width, int height, SDL_PixelFormat format);

 /**
- * Allocate a new RGB 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.
@@ -171,11 +150,11 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurface(int width, int height
 * You may pass NULL for pixels and 0 for pitch to create a surface that you
 * will fill in with valid values later.
 *
- * \param pixels a pointer to existing pixel data.
 * \param width the width of the surface.
 * \param height the height of the surface.
+ * \param format the SDL_PixelFormat for the new surface's pixel format.
+ * \param pixels a pointer to existing pixel data.
 * \param pitch the number of bytes between each row, including padding.
- * \param format the SDL_PixelFormatEnum for the new surface's pixel format.
 * \returns the new SDL_Surface structure that is created or NULL if it fails;
 *          call SDL_GetError() for more information.
 *
@@ -184,10 +163,10 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurface(int width, int height
 * \sa SDL_CreateSurface
 * \sa SDL_DestroySurface
 */
-extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurfaceFrom(void *pixels, int width, int height, int pitch, SDL_PixelFormatEnum format);
+extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurfaceFrom(int width, int height, SDL_PixelFormat format, void *pixels, int pitch);

 /**
- * Free an RGB surface.
+ * Free a surface.
 *
 * It is safe to pass NULL to this function.
 *
@@ -195,6 +174,7 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurfaceFrom(void *pixels, int
 *
 * \since This function is available since SDL 3.0.0.
 *
+ * \sa SDL_CreateStackSurface
 * \sa SDL_CreateSurface
 * \sa SDL_CreateSurfaceFrom
 */
@@ -254,6 +234,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSurfaceProperties(SDL_Surfac
 *          SDL_GetError() for more information.
 *
 * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_GetSurfaceColorspace
 */
 extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace colorspace);

@@ -265,14 +247,13 @@ 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.
- * \param colorspace a pointer filled in with an SDL_ColorSpace value
- *                   describing the surface colorspace.
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * \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.
+ *
+ * \sa SDL_SetSurfaceColorspace
 */
-extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorspace(SDL_Surface *surface, SDL_Colorspace *colorspace);
+extern SDL_DECLSPEC SDL_Colorspace SDLCALL SDL_GetSurfaceColorspace(SDL_Surface *surface);

 /**
 * Set the palette used by a surface.
@@ -285,9 +266,24 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSurfaceColorspace(SDL_Surface *surface, S
 *          SDL_GetError() for more information.
 *
 * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_CreatePalette
+ * \sa SDL_GetSurfacePalette
 */
 extern SDL_DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette);

+/**
+ * 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.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_SetSurfacePalette
+ */
+extern SDL_DECLSPEC SDL_Palette * SDLCALL SDL_GetSurfacePalette(SDL_Surface *surface);
+
 /**
 * Set up a surface for directly accessing the pixels.
 *
@@ -411,7 +407,7 @@ 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 flag 0 to disable, non-zero to enable RLE acceleration.
+ * \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.
 *
@@ -421,7 +417,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SaveBMP(SDL_Surface *surface, const char *fi
 * \sa SDL_LockSurface
 * \sa SDL_UnlockSurface
 */
-extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, int flag);
+extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface *surface, SDL_bool enabled);

 /**
 * Returns whether the surface is RLE enabled.
@@ -447,11 +443,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface);
 * It is a pixel of the format used by the surface, as generated by
 * SDL_MapRGB().
 *
- * RLE acceleration can substantially speed up blitting of images with large
- * horizontal runs of transparent pixels. See SDL_SetSurfaceRLE() for details.
- *
 * \param surface the SDL_Surface structure to update.
- * \param flag 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.
@@ -459,9 +452,10 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasRLE(SDL_Surface *surface);
 * \since This function is available since SDL 3.0.0.
 *
 * \sa SDL_GetSurfaceColorKey
+ * \sa SDL_SetSurfaceRLE
 * \sa SDL_SurfaceHasColorKey
 */
-extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, int flag, Uint32 key);
+extern SDL_DECLSPEC int SDLCALL SDL_SetSurfaceColorKey(SDL_Surface *surface, SDL_bool enabled, Uint32 key);

 /**
 * Returns whether the surface has a color key.
@@ -681,41 +675,19 @@ 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.
+ *
 * \param surface the existing SDL_Surface structure to convert.
- * \param format the SDL_PixelFormat structure that the new surface is
- *               optimized for.
+ * \param format the new pixel format.
 * \returns the new SDL_Surface structure that is created or NULL if it fails;
 *          call SDL_GetError() for more information.
 *
 * \since This function is available since SDL 3.0.0.
 *
- * \sa SDL_ConvertSurfaceFormat
- * \sa SDL_ConvertSurfaceFormatAndColorspace
- * \sa SDL_CreatePixelFormat
+ * \sa SDL_ConvertSurfaceAndColorspace
 * \sa SDL_DestroySurface
 */
-extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface(SDL_Surface *surface, const SDL_PixelFormat *format);
-
-/**
- * Copy an existing surface to a new surface of the specified format.
- *
- * This function operates just like SDL_ConvertSurface(), but accepts an
- * SDL_PixelFormatEnum value instead of an SDL_PixelFormat structure. As such,
- * it might be easier to call but it doesn't have access to palette
- * information for the destination surface, in case that would be important.
- *
- * \param surface the existing SDL_Surface structure to convert.
- * \param pixel_format the new pixel format.
- * \returns the new SDL_Surface structure that is created or NULL if it fails;
- *          call SDL_GetError() for more information.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_ConvertSurface
- * \sa SDL_ConvertSurfaceFormatAndColorspace
- * \sa SDL_DestroySurface
- */
-extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat(SDL_Surface *surface, SDL_PixelFormatEnum pixel_format);
+extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface(SDL_Surface *surface, SDL_PixelFormat format);

 /**
 * Copy an existing surface to a new surface of the specified format and
@@ -726,7 +698,8 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat(SDL_Surface *s
 * colorspace conversion needed.
 *
 * \param surface the existing SDL_Surface structure to convert.
- * \param pixel_format the new pixel format.
+ * \param format the new pixel format.
+ * \param palette an optional palette to use for indexed formats, may be NULL.
 * \param colorspace the new colorspace.
 * \param props an SDL_PropertiesID with additional color properties, or 0.
 * \returns the new SDL_Surface structure that is created or NULL if it fails;
@@ -735,20 +708,20 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat(SDL_Surface *s
 * \since This function is available since SDL 3.0.0.
 *
 * \sa SDL_ConvertSurface
- * \sa SDL_ConvertSurfaceFormat
+ * \sa SDL_ConvertSurface
 * \sa SDL_DestroySurface
 */
-extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormatAndColorspace(SDL_Surface *surface, SDL_PixelFormatEnum pixel_format, SDL_Colorspace colorspace, SDL_PropertiesID props);
+extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceAndColorspace(SDL_Surface *surface, SDL_PixelFormat format, const SDL_Palette *palette, SDL_Colorspace colorspace, SDL_PropertiesID props);

 /**
 * Copy a block of pixels of one format to another format.
 *
 * \param width the width of the block to copy, in pixels.
 * \param height the height of the block to copy, in pixels.
- * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format.
+ * \param src_format an SDL_PixelFormat value of the `src` pixels format.
 * \param src a pointer to the source pixels.
 * \param src_pitch the pitch of the source pixels, in bytes.
- * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format.
+ * \param dst_format an SDL_PixelFormat value of the `dst` pixels format.
 * \param dst a pointer to be filled in with new pixel data.
 * \param dst_pitch the pitch of the destination pixels, in bytes.
 * \returns 0 on success or a negative error code on failure; call
@@ -758,7 +731,7 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormatAndColorspace(S
 *
 * \sa SDL_ConvertPixelsAndColorspace
 */
-extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormatEnum src_format, const void *src, int src_pitch, SDL_PixelFormatEnum dst_format, void *dst, int dst_pitch);
+extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch);

 /**
 * Copy a block of pixels of one format and colorspace to another format and
@@ -766,14 +739,14 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, SDL_Pix
 *
 * \param width the width of the block to copy, in pixels.
 * \param height the height of the block to copy, in pixels.
- * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format.
+ * \param src_format an SDL_PixelFormat value of the `src` pixels format.
 * \param src_colorspace an SDL_ColorSpace value describing the colorspace of
 *                       the `src` pixels.
 * \param src_properties an SDL_PropertiesID with additional source color
 *                       properties, or 0.
 * \param src a pointer to the source pixels.
 * \param src_pitch the pitch of the source pixels, in bytes.
- * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format.
+ * \param dst_format an SDL_PixelFormat value of the `dst` pixels format.
 * \param dst_colorspace an SDL_ColorSpace value describing the colorspace of
 *                       the `dst` pixels.
 * \param dst_properties an SDL_PropertiesID with additional destination color
@@ -787,7 +760,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, SDL_Pix
 *
 * \sa SDL_ConvertPixels
 */
-extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormatEnum src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormatEnum dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch);
+extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixelsAndColorspace(int width, int height, SDL_PixelFormat src_format, SDL_Colorspace src_colorspace, SDL_PropertiesID src_properties, const void *src, int src_pitch, SDL_PixelFormat dst_format, SDL_Colorspace dst_colorspace, SDL_PropertiesID dst_properties, void *dst, int dst_pitch);

 /**
 * Premultiply the alpha on a block of pixels.
@@ -798,10 +771,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixelsAndColorspace(int width, int he
 *
 * \param width the width of the block to convert, in pixels.
 * \param height the height of the block to convert, in pixels.
- * \param src_format an SDL_PixelFormatEnum value of the `src` pixels format.
+ * \param src_format an SDL_PixelFormat value of the `src` pixels format.
 * \param src a pointer to the source pixels.
 * \param src_pitch the pitch of the source pixels, in bytes.
- * \param dst_format an SDL_PixelFormatEnum value of the `dst` pixels format.
+ * \param dst_format an SDL_PixelFormat value of the `dst` pixels format.
 * \param dst a pointer to be filled in with premultiplied pixel data.
 * \param dst_pitch the pitch of the destination pixels, in bytes.
 * \returns 0 on success or a negative error code on failure; call
@@ -809,7 +782,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertPixelsAndColorspace(int width, int he
 *
 * \since This function is available since SDL 3.0.0.
 */
-extern SDL_DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormatEnum src_format, const void *src, int src_pitch, SDL_PixelFormatEnum dst_format, void *dst, int dst_pitch);
+extern SDL_DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height, SDL_PixelFormat src_format, const void *src, int src_pitch, SDL_PixelFormat dst_format, void *dst, int dst_pitch);

 /**
 * Perform a fast fill of a rectangle with a specific color.
@@ -1033,6 +1006,67 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SD
 */
 extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled(SDL_Surface *src, const SDL_Rect *srcrect, SDL_Surface *dst, const SDL_Rect *dstrect, SDL_ScaleMode scaleMode);

+/**
+ * Map an RGB triple to an opaque pixel value for a surface.
+ *
+ * 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.
+ *
+ * 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).
+ *
+ * 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 surface the surface to use for the pixel format and palette.
+ * \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 3.0.0.
+ *
+ * \sa SDL_MapSurfaceRGBA
+ */
+extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGB(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b);
+
+/**
+ * Map an RGBA quadruple to a pixel value for a surface.
+ *
+ * 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 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 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 surface the surface to use for the pixel format and palette.
+ * \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 3.0.0.
+ *
+ * \sa SDL_MapSurfaceRGB
+ */
+extern SDL_DECLSPEC Uint32 SDLCALL SDL_MapSurfaceRGBA(SDL_Surface *surface, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
+
 /**
 * Retrieves a single pixel from a surface.
 *
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -88,7 +88,7 @@ typedef enum SDL_SystemTheme
 typedef struct SDL_DisplayMode
 {
    SDL_DisplayID displayID;    /**< the display this mode is associated with */
-    SDL_PixelFormatEnum format; /**< pixel format */
+    SDL_PixelFormat format;     /**< pixel format */
    int w;                      /**< width */
    int h;                      /**< height */
    float pixel_density;        /**< scale converting size to pixels (e.g. a 1920x1080 mode with 2.0 scale would have 3840x2160 pixels) */