Fixed bug 3352 - Adding alpha mask support to SDL_SaveBMP_RW

Simon Hug

The current SDL_SaveBMP_RW function that saves surfaces to a BMP uses an old bitmap header which doesn't officially support alpha channels. Applications just ignore the byte where the alpha is stored. This can easily be extended by using a newer header version and setting the alpha mask.

The attached patch has these changes:

- Extending the description of the function in the SDL_surface.h header with the supported formats.
- Refining when surfaces get stored to a 32-bit BMP. (Must have bit depth of 8 or higher and must have an alpha mask or colorkey.)
- Fixing a small bug that saves 24-bit BGR surfaces with a colorkey in a 24-bit BMP.
- Adding code that switches to the bitmap header version 4 if the surface has an alpha mask or colorkey. (I chose version 4 because Microsoft didn't lose its documentation behind a file cabinet like they did with version 3.)
- Adding a hint that can disable the use of the version 4 header. This is for people that need the legacy header or like the old behavior better. (I'm not sure about the hint name, though. May need changing if there are any rules to that.)

include/SDL_surface.h

@@ -184,6 +184,12 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src,
 /**
  *  Save a surface to a seekable SDL data stream (memory or file).
  *
+ *  Surfaces with a 24-bit, 32-bit and paletted 8-bit format get saved in the
+ *  BMP directly. Other RGB formats with 8-bit or higher get converted to a
+ *  24-bit surface or, if they have an alpha mask or a colorkey, to a 32-bit
+ *  surface before they are saved. YUV and paletted 1-bit and 4-bit formats are
+ *  not supported.
+ *
  *  If \c freedst is non-zero, the stream will be closed after being written.
  *
  *  \return 0 if successful or -1 if there was an error.