Clarified the migration path for SDL_CreateSurface()

WhatsNew.txt

@@ -12,26 +12,22 @@ General:
 * The preprocessor symbol __MACOSX__ has been renamed __MACOS__
 * The preprocessor symbol __IPHONEOS__ has been renamed __IOS__
 * Removed the following functions from the API, see docs/README-migration.md for details:
-	* SDL_CalculateGammaRamp()
-	* SDL_GetRevisionNumber()
-	* SDL_GetWindowBrightness()
-	* SDL_GetWindowGammaRamp()
-	* SDL_RWFromFP()
-	* SDL_SetWindowBrightness()
-	* SDL_SetWindowGammaRamp()
-   * SDL_CreateRGBSurface()
-   * SDL_CreateRGBSurfaceWithFormat()
-   * SDL_CreateRGBSurfaceFrom()
-   * SDL_CreateRGBSurfaceWithFormatFrom()
+    * SDL_CalculateGammaRamp()
+    * SDL_GetRevisionNumber()
+    * SDL_GetWindowBrightness()
+    * SDL_GetWindowGammaRamp()
+    * SDL_RWFromFP()
+    * SDL_SetWindowBrightness()
+    * SDL_SetWindowGammaRamp()
+    * SDL_CreateRGBSurface()
+    * SDL_CreateRGBSurfaceWithFormat()
+    * SDL_CreateRGBSurfaceFrom()
+    * SDL_CreateRGBSurfaceWithFormatFrom()
 * Removed the following hints from the API, see docs/README-migration.md for details:
-	* SDL_HINT_IDLE_TIMER_DISABLED
-	* SDL_HINT_VIDEO_X11_FORCE_EGL
-	* SDL_HINT_VIDEO_X11_XINERAMA
-	* SDL_HINT_VIDEO_X11_XVIDMODE
+    * SDL_HINT_IDLE_TIMER_DISABLED
+    * SDL_HINT_VIDEO_X11_FORCE_EGL
+    * SDL_HINT_VIDEO_X11_XINERAMA
+    * SDL_HINT_VIDEO_X11_XVIDMODE
 * SDL_stdinc.h no longer includes stdio.h, stdlib.h, etc., it only provides the SDL C runtime functionality
+* Added SDL_CreateSurface() and SDL_CreateSurfaceFrom() which replace the SDL_CreateRGBSurface*()
 * Removed unused 'flags' parameter from SDL_ConvertSurface and SDL_ConvertSurfaceFormat
-* Added SDL_CreateSurface() and SDL_CreateSurfaceFrom() which take a format. SDL_CreateRGBSurface*() are removed.
-
-
-
-

docs/README-migration.md

@@ -164,33 +164,42 @@ M_PI is no longer defined in SDL_stdinc.h, you can use the new symbols SDL_PI_D
 
 Removed unused 'flags' parameter from SDL_ConvertSurface and SDL_ConvertSurfaceFormat.
 
+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().
 
-Added SDL_CreateSurface() and SDL_CreateSurfaceFrom() which take a format.
-SDL_CreateRGBSurface(), SDL_CreateRGBSurfaceFrom(), SDL_CreateRGBSurfaceWithFormat() and SDL_CreateRGBSurfaceWithFormatFrom() are removed.
-
-This code:
-
+You can implement the old functions in your own code easily:
 ```c
-SDL_Surface *surface = SDL_CreateRGBSurface(0, width, height, 0, Rmask, Gmask, Bmask, Amask);
-```
+SDL_Surface *SDL_CreateRGBSurfaceWithFormat(Uint32 flags, int width, int height, int depth, Uint32 format)
+{
+    return SDL_CreateSurface(width, height, format);
+}
 
-can be replaced with this:
+SDL_Surface * SDL_CreateRGBSurfaceWithFormatFrom(void *pixels, int width, int height, int depth, int pitch, Uint32 format)
+{
+    return SDL_CreateSurfaceFrom(pixels, width, height, pitch, format);
+}
 
-```c
-Uint32 format = SDL_MasksToPixelFormatEnum(0, Rmask, Gmask, Bmask, Amask);
-SDL_Surface *surface = SDL_CreateSurface(width, height, format);
-```
+SDL_Surface *SDL_CreateRGBSurface(Uint32 flags, int width, int height, int depth, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
+{
+    return SDL_CreateRGBSurfaceWithFormat(flags, width, height, depth,
+            SDL_MasksToPixelFormatEnum(depth, Rmask, Gmask, Bmask, Amask));
+}
 
-but in general, you probably have a format that you know you're using, possibly one of these:
+SDL_Surface *SDL_CreateRGBSurfaceFrom(void *pixels, int width, int height, int depth, int pitch, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
+{
+    return SDL_CreateRGBSurfaceWithFormatFrom(pixels, width, height, depth, pitch,
+            SDL_MasksToPixelFormatEnum(depth, Rmask, Gmask, Bmask, Amask));
+}
 
+```
 
+But if you're migrating your code which uses masks, you probably have a format in mind, possibly one of these:
 ```c
-// Various mask (R, G, B, A) in little endian and their corresponding format:
+// Various mask (R, G, B, A) and their corresponding format:
 0xFF000000 0x00FF0000 0x0000FF00 0x000000FF => SDL_PIXELFORMAT_RGBA8888
-0x000000FF 0x0000FF00 0x00FF0000 0xFF000000 => SDL_PIXELFORMAT_ABGR8888
 0x00FF0000 0x0000FF00 0x000000FF 0xFF000000 => SDL_PIXELFORMAT_ARGB8888
-0x00FF0000 0x0000FF00 0x000000FF 0x00000000 => SDL_PIXELFORMAT_BGR24
-0x000000FF 0x0000FF00 0x000000FF 0x00000000 => SDL_PIXELFORMAT_RGB24
+0x0000FF00 0x00FF0000 0xFF000000 0x000000FF => SDL_PIXELFORMAT_BGRA8888
+0x000000FF 0x0000FF00 0x00FF0000 0xFF000000 => SDL_PIXELFORMAT_ABGR8888
 0x00007C00 00000x03E0 00000x001F 0x00000000 => SDL_PIXELFORMAT_RGB555
 0x00007C00 00000x03E0 00000x001F 0x00008000 => SDL_PIXELFORMAT_ARGB1555
 ```