Sync wiki -> header
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
diff --git a/include/SDL_surface.h b/include/SDL_surface.h
index 0634ab9..1a145cc 100644
--- a/include/SDL_surface.h
+++ b/include/SDL_surface.h
@@ -305,7 +305,35 @@ extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
/**
* Load a BMP image from a seekable SDL data stream.
*
- * The new surface should be freed with SDL_FreeSurface().
+ * The new surface should be freed with SDL_FreeSurface(). Not doing so will
+ * result in a memory leak.
+ *
+ * src is an open SDL_RWops buffer, typically loaded with SDL_RWFromFile.
+ * Alternitavely, you might also use the macro SDL_LoadBMP to load a bitmap
+ * from a file, convert it to an SDL_Surface and then close the file.
+ *
+ * === Code Example ===
+ *
+ * ```c++
+ * const char *image_path = "myimage.bmp";
+ *
+ * /* "rb" will "read binary" files */
+ * SDL_RWops *file = SDL_RWFromFile(image_path, "rb");
+ *
+ * /* freesrc is true so the file automatically closes */
+ * SDL_Surface *image = SDL_LoadBMP_RW(file, SDL_TRUE);
+ *
+ * /* Let the user know if the file failed to load */
+ * if (!image) {
+ * printf("Failed to load image at %s: %s\n", image_path, SDL_GetError());
+ * return;
+ * }
+ *
+ * /* Do something with image here. */
+ *
+ * /* Make sure to eventually release the surface resource */
+ * SDL_FreeSurface(image);
+ * ```
*
* \param src the data stream for the surface
* \param freesrc non-zero to close the stream after being read
@@ -313,6 +341,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface);
* error; call SDL_GetError() for more information.
*
* \sa SDL_FreeSurface
+ * \sa SDL_RWFromFile
* \sa SDL_LoadBMP
* \sa SDL_SaveBMP_RW
*/