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.

VisualC-GDK/SDL/SDL.vcxproj

@@ -558,6 +558,7 @@
     <ClInclude Include="..\..\src\video\SDL_pixels_c.h" />
     <ClInclude Include="..\..\src\video\SDL_rect_c.h" />
     <ClInclude Include="..\..\src\video\SDL_RLEaccel_c.h" />
+    <ClInclude Include="..\..\src\video\SDL_surface_c.h" />
     <ClInclude Include="..\..\src\video\SDL_sysvideo.h" />
     <ClInclude Include="..\..\src\video\SDL_vulkan_internal.h" />
     <ClInclude Include="..\..\src\video\SDL_yuv_c.h" />
@@ -863,4 +864,4 @@
   <ImportGroup Label="ExtensionTargets">
     <Import Project="$(VCTargetsPath)\BuildCustomizations\masm.targets" />
   </ImportGroup>
-</Project>
+</Project>

VisualC-GDK/SDL/SDL.vcxproj.filters

@@ -436,6 +436,7 @@
     <ClInclude Include="..\..\src\video\SDL_pixels_c.h" />
     <ClInclude Include="..\..\src\video\SDL_rect_c.h" />
     <ClInclude Include="..\..\src\video\SDL_RLEaccel_c.h" />
+    <ClInclude Include="..\..\src\video\SDL_surface_c.h" />
     <ClInclude Include="..\..\src\video\SDL_sysvideo.h" />
     <ClInclude Include="..\..\src\video\SDL_vulkan_internal.h" />
     <ClInclude Include="..\..\src\video\SDL_yuv_c.h" />
@@ -462,4 +463,4 @@
   <ItemGroup>
     <ResourceCompile Include="..\..\src\core\windows\version.rc" />
   </ItemGroup>
-</Project>
+</Project>

VisualC-WinRT/SDL-UWP.vcxproj

@@ -185,6 +185,7 @@
     <ClInclude Include="..\src\video\SDL_pixels_c.h" />
     <ClInclude Include="..\src\video\SDL_rect_c.h" />
     <ClInclude Include="..\src\video\SDL_RLEaccel_c.h" />
+    <ClInclude Include="..\src\video\SDL_surface_c.h" />
     <ClInclude Include="..\src\video\SDL_sysvideo.h" />
     <ClInclude Include="..\src\video\SDL_sysvidocapture.h" />
     <ClInclude Include="..\src\video\SDL_yuv_c.h" />
@@ -917,4 +918,4 @@
   <ImportGroup Label="ExtensionTargets">
     <Import Project="$(VCTargetsPath)\BuildCustomizations\masm.targets" />
   </ImportGroup>
-</Project>
+</Project>

VisualC-WinRT/SDL-UWP.vcxproj.filters

@@ -438,6 +438,9 @@
     <ClInclude Include="..\src\video\SDL_RLEaccel_c.h">
       <Filter>Source Files</Filter>
     </ClInclude>
+    <ClInclude Include="..\src\video\SDL_surface_c.h">
+      <Filter>Source Files</Filter>
+    </ClInclude>
     <ClInclude Include="..\src\video\SDL_sysvideo.h">
       <Filter>Source Files</Filter>
     </ClInclude>
@@ -973,4 +976,4 @@
       <Filter>Source Files</Filter>
     </ClCompile>
   </ItemGroup>
-</Project>
+</Project>

VisualC/SDL/SDL.vcxproj

@@ -464,6 +464,7 @@
     <ClInclude Include="..\..\src\video\SDL_pixels_c.h" />
     <ClInclude Include="..\..\src\video\SDL_rect_c.h" />
     <ClInclude Include="..\..\src\video\SDL_RLEaccel_c.h" />
+    <ClInclude Include="..\..\src\video\SDL_surface_c.h" />
     <ClInclude Include="..\..\src\video\SDL_sysvideo.h" />
     <ClInclude Include="..\..\src\video\SDL_vulkan_internal.h" />
     <ClInclude Include="..\..\src\video\SDL_yuv_c.h" />

VisualC/SDL/SDL.vcxproj.filters

@@ -615,6 +615,9 @@
     <ClInclude Include="..\..\src\video\SDL_RLEaccel_c.h">
       <Filter>video</Filter>
     </ClInclude>
+    <ClInclude Include="..\..\src\video\SDL_surface_c.h">
+      <Filter>video</Filter>
+    </ClInclude>
     <ClInclude Include="..\..\src\video\SDL_blit.h">
       <Filter>video</Filter>
     </ClInclude>
@@ -1554,4 +1557,4 @@
   <ItemGroup>
     <MASM Include="..\..\src\stdlib\SDL_mslibc_x64.masm" />
   </ItemGroup>
-</Project>
+</Project>

build-scripts/SDL_migration.cocci

@@ -1566,7 +1566,7 @@ typedef SDL_GameControllerButton, SDL_GamepadButton;
 @@
 @@
 - SDL_AllocFormat
-+ SDL_CreatePixelFormat
++ SDL_GetPixelFormatDetails
   (...)
 @@
 @@
@@ -1575,23 +1575,18 @@ typedef SDL_GameControllerButton, SDL_GamepadButton;
   (...)
 @@
 @@
-- SDL_FreeFormat
-+ SDL_DestroyPixelFormat
-  (...)
-@@
-@@
 - SDL_FreePalette
 + SDL_DestroyPalette
   (...)
 @@
 @@
 - SDL_MasksToPixelFormatEnum
-+ SDL_GetPixelFormatEnumForMasks
++ SDL_GetPixelFormatForMasks
   (...)
 @@
 @@
 - SDL_PixelFormatEnumToMasks
-+ SDL_GetMasksForPixelFormatEnum
++ SDL_GetMasksForPixelFormat
   (...)
 @@
 @@
@@ -3488,3 +3483,21 @@ typedef SDL_Colour, SDL_Color;
 @@
 - SDLK_z
 + SDLK_Z
+@@
+typedef SDL_PixelFormat, SDL_PackedPixelDetails;
+@@
+- SDL_PixelFormat
++ SDL_PixelFormatDetails
+@@
+@@
+- SDL_ConvertSurfaceFormat
++ SDL_ConvertSurface
+  (...)
+@@
+@@
+- SDL_PREALLOC
++ SDL_SURFACE_PREALLOCATED
+@@
+@@
+- SDL_SIMD_ALIGNED
++ SDL_SURFACE_SIMD_ALIGNED

cmake/test/main_gui.c

@@ -15,7 +15,7 @@ int main(int argc, char *argv[])
         return 1;
     }
     screenSurface = SDL_GetWindowSurface(window);
-    SDL_FillSurfaceRect(screenSurface, NULL, SDL_MapRGB(screenSurface->format, 0xff, 0xff, 0xff));
+    SDL_FillSurfaceRect(screenSurface, NULL, SDL_MapSurfaceRGB(screenSurface, 0xff, 0xff, 0xff));
     SDL_UpdateWindowSurface(window);
     SDL_Delay(100);
     SDL_DestroyWindow(window);

docs/README-migration.md

@@ -1092,19 +1092,22 @@ The following symbols have been renamed:
 
 ## SDL_pixels.h
 
-SDL_CalculateGammaRamp has been removed, because SDL_SetWindowGammaRamp has been removed as well due to poor support in modern operating systems (see [SDL_video.h](#sdl_videoh)).
+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.
 
-The BitsPerPixel and BytesPerPixel fields of SDL_PixelFormat have been renamed bits_per_pixel and bytes_per_pixel.
+SDL_MapRGB(), SDL_MapRGBA(), SDL_GetRGB(), and SDL_GetRGBA() take an optional palette parameter for indexed color lookups.
 
-SDL_PixelFormatEnum is used instead of Uint32 for API functions that refer to pixel format by enumerated value.
+SDL_GetMasksForPixelFormat() now returns the standard int error code.
+
+SDL_CalculateGammaRamp has been removed, because SDL_SetWindowGammaRamp has been removed as well due to poor support in modern operating systems (see [SDL_video.h](#sdl_videoh)).
 
 The following functions have been renamed:
-* SDL_AllocFormat() => SDL_CreatePixelFormat()
+* SDL_AllocFormat() => SDL_GetPixelFormatDetails()
 * SDL_AllocPalette() => SDL_CreatePalette()
-* SDL_FreeFormat() => SDL_DestroyPixelFormat()
 * SDL_FreePalette() => SDL_DestroyPalette()
-* SDL_MasksToPixelFormatEnum() => SDL_GetPixelFormatEnumForMasks()
-* SDL_PixelFormatEnumToMasks() => SDL_GetMasksForPixelFormatEnum()
+* SDL_MasksToPixelFormatEnum() => SDL_GetPixelFormatForMasks()
+* SDL_PixelFormatEnumToMasks() => SDL_GetMasksForPixelFormat()
 
 The following symbols have been renamed:
 * SDL_PIXELFORMAT_BGR444 => SDL_PIXELFORMAT_XBGR4444
@@ -1114,9 +1117,16 @@ The following symbols have been renamed:
 * SDL_PIXELFORMAT_RGB555 => SDL_PIXELFORMAT_XRGB1555
 * SDL_PIXELFORMAT_RGB888 => SDL_PIXELFORMAT_XRGB8888
 
+The following functions have been removed:
+* SDL_FreeFormat()
+* SDL_SetPixelFormatPalette()
+
 The following macros have been removed:
 * SDL_Colour - use SDL_Color instead
 
+The following structures have been renamed:
+* SDL_PixelFormat => SDL_PixelFormatDetails
+
 ## SDL_platform.h
 
 The following platform preprocessor macros have been renamed:
@@ -1598,19 +1608,23 @@ The following functions have been removed:
 
 ## SDL_surface.h
 
+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().
+
 The userdata member of SDL_Surface has been replaced with a more general properties interface, which can be queried with SDL_GetSurfaceProperties()
 
-Removed unused 'flags' parameter from SDL_ConvertSurface and SDL_ConvertSurfaceFormat.
+Removed the unused 'flags' parameter from SDL_ConvertSurface.
 
 SDL_CreateRGBSurface() and SDL_CreateRGBSurfaceWithFormat() have been combined into a new function SDL_CreateSurface().
-SDL_CreateRGBSurfaceFrom() and SDL_CreateRGBSurfaceWithFormatFrom() have been combined into a new function SDL_CreateSurfaceFrom().
+SDL_CreateRGBSurfaceFrom() and SDL_CreateRGBSurfaceWithFormatFrom() have been combined into a new function SDL_CreateSurfaceFrom(), and the parameter order has changed for consistency with SDL_CreateSurface().
 
 You can implement the old functions in your own code easily:
 ```c
 SDL_Surface *SDL_CreateRGBSurface(Uint32 flags, int width, int height, int depth, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
 {
     return SDL_CreateSurface(width, height,
-            SDL_GetPixelFormatEnumForMasks(depth, Rmask, Gmask, Bmask, Amask));
+            SDL_GetPixelFormatForMasks(depth, Rmask, Gmask, Bmask, Amask));
 }
 
 SDL_Surface *SDL_CreateRGBSurfaceWithFormat(Uint32 flags, int width, int height, int depth, Uint32 format)
@@ -1620,13 +1634,14 @@ SDL_Surface *SDL_CreateRGBSurfaceWithFormat(Uint32 flags, int width, int height,
 
 SDL_Surface *SDL_CreateRGBSurfaceFrom(void *pixels, int width, int height, int depth, int pitch, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
 {
-    return SDL_CreateSurfaceFrom(pixels, width, height, pitch,
-            SDL_GetPixelFormatEnumForMasks(depth, Rmask, Gmask, Bmask, Amask));
+    return SDL_CreateSurfaceFrom(width, height,
+                                 SDL_GetPixelFormatForMasks(depth, Rmask, Gmask, Bmask, Amask),
+                                 pixels, pitch);
 }
 
 SDL_Surface *SDL_CreateRGBSurfaceWithFormatFrom(void *pixels, int width, int height, int depth, int pitch, Uint32 format)
 {
-    return SDL_CreateSurfaceFrom(pixels, width, height, pitch, format);
+    return SDL_CreateSurfaceFrom(width, height, format, pixels, pitch);
 }
 
 ```
@@ -1645,10 +1660,15 @@ SDL_BlitSurfaceScaled() and SDL_BlitSurfaceUncheckedScaled() now take a scale pa
 
 SDL_SoftStretch() now takes a scale paramater.
 
-SDL_PixelFormatEnum is used instead of Uint32 for API functions that refer to pixel format by enumerated value.
+SDL_PixelFormat is used instead of Uint32 for API functions that refer to pixel format by enumerated value.
+
+SDL_SetSurfaceColorKey() takes an SDL_bool to enable and disable colorkey. RLE acceleration isn't controlled by the parameter, you should use SDL_SetSurfaceRLE() to change that separately.
+
+SDL_SetSurfaceRLE() takes an SDL_bool to enable and disable RLE acceleration.
 
 The following functions have been renamed:
 * SDL_BlitScaled() => SDL_BlitSurfaceScaled()
+* SDL_ConvertSurfaceFormat() => SDL_ConvertSurface()
 * SDL_FillRect() => SDL_FillSurfaceRect()
 * SDL_FillRects() => SDL_FillSurfaceRects()
 * SDL_FreeSurface() => SDL_DestroySurface()
@@ -1669,11 +1689,16 @@ The following symbols have been removed:
 * SDL_SWSURFACE
 
 The following functions have been removed:
+* SDL_FreeFormat()
 * SDL_GetYUVConversionMode()
 * SDL_GetYUVConversionModeForResolution()
 * SDL_SetYUVConversionMode() - use SDL_SetSurfaceColorspace() to set the surface colorspace and SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER with SDL_CreateTextureWithProperties() to set the texture colorspace. The default colorspace for YUV pixel formats is SDL_COLORSPACE_JPEG.
 * SDL_SoftStretchLinear() - use SDL_SoftStretch() with SDL_SCALEMODE_LINEAR
 
+The following symbols have been renamed:
+* SDL_PREALLOC => SDL_SURFACE_PREALLOCATED
+* SDL_SIMD_ALIGNED => SDL_SURFACE_SIMD_ALIGNED
+
 ## SDL_system.h
 
 SDL_WindowsMessageHook has changed signatures so the message may be modified and it can block further message processing.
@@ -1835,7 +1860,7 @@ The callback passed to SDL_AddTimer() has changed parameters to:
 Uint32 SDLCALL TimerCallback(void *userdata, SDL_TimerID timerID, Uint32 interval);
 ````
 
-The return value of SDL_RemoveTimer() has changed to the standard int error code.
+SDL_RemoveTimer() now returns the standard int error code.
 
 ## SDL_touch.h
 

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 */

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