|
Size: 2085
Comment: clarify what the format argument is, link SDL_PixelFormatEnum there
|
Size: 3125
Comment: add code example
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 41: | Line 41: |
| You can add your code example here | // This example shows how to create a SDL_Surface* with the data loaded // from an image file with stb_image.h (https://github.com/nothings/stb/) // the color format you request stb_image to output, // use STBI_rgb if you don't want/need the alpha channel int req_format = STBI_rgb_alpha; int width, height, orig_format; unsigned char* data = stbi_load("./test.png", &width, &height, &orig_format, req_format); if(data == NULL) { fprintf(stderr, "Loading image failed: %s\n", stbi_failure_reason()); exit(1); } int depth, pitch; Uint32 pixel_format; if(req_format == STBI_rgb) { depth = 24; pitch = 3*width; // 3 bytes per pixel * pixels per row pixel_format = SDL_PIXELFORMAT_RGB24; } else { // STBI_rgb_alpha (RGBA) depth = 32; pitch = 4*width; pixel_format = SDL_PIXELFORMAT_RGBA32; } SDL_Surface* surf = SDL_CreateRGBSurfaceWithFormatFrom((void*)data, width, height, depth, pitch, pixel_format); if(surf == NULL) { fprintf(stderr, "Creating surface failed: %s\n", SDL_GetError()); stbi_image_free(data); exit(1); } // ... do something useful with the surface ... // ... // when you don't need the surface anymore, free it.. SDL_FreeSurface(surf); // .. *and* the data used by the surface! stbi_image_free(data); |
| Line 43: | Line 83: |
##Leave this section as-is unless you have a code example to put in. In that case, replace You can add your code example here with your code example following the Style Guide instructions. Leave the rest of the markup alone and delete this comment. |
DRAFT |
SDL_CreateRGBSurfaceWithFormatFrom
Use this function to allocate an RGB surface from provided pixel data.
Contents
Syntax
SDL_Surface* SDL_CreateRGBSurfaceWithFormatFrom(void* pixels,
int width,
int height,
int depth,
int pitch,
Uint32 format)
Function Parameters
pixels |
the pixel data to create the surface from |
width |
the width in pixels of the surface to create |
height |
the height in pixels of the surface to create |
depth |
the depth in bits of the surface to create |
pitch |
the number of bytes in a row in pixels |
format |
the pixel format of the surface to create |
Return Value
Returns a new SDL_Surface on success or NULL on failure; call SDL_GetError() for more information.
Code Examples
// This example shows how to create a SDL_Surface* with the data loaded
// from an image file with stb_image.h (https://github.com/nothings/stb/)
// the color format you request stb_image to output,
// use STBI_rgb if you don't want/need the alpha channel
int req_format = STBI_rgb_alpha;
int width, height, orig_format;
unsigned char* data = stbi_load("./test.png", &width, &height, &orig_format, req_format);
if(data == NULL) {
fprintf(stderr, "Loading image failed: %s\n", stbi_failure_reason());
exit(1);
}
int depth, pitch;
Uint32 pixel_format;
if(req_format == STBI_rgb) {
depth = 24;
pitch = 3*width; // 3 bytes per pixel * pixels per row
pixel_format = SDL_PIXELFORMAT_RGB24;
} else { // STBI_rgb_alpha (RGBA)
depth = 32;
pitch = 4*width;
pixel_format = SDL_PIXELFORMAT_RGBA32;
}
SDL_Surface* surf = SDL_CreateRGBSurfaceWithFormatFrom((void*)data, width, height,
depth, pitch, pixel_format);
if(surf == NULL) {
fprintf(stderr, "Creating surface failed: %s\n", SDL_GetError());
stbi_image_free(data);
exit(1);
}
// ... do something useful with the surface ...
// ...
// when you don't need the surface anymore, free it..
SDL_FreeSurface(surf);
// .. *and* the data used by the surface!
stbi_image_free(data);
Remarks
If the function runs out of memory, it will return NULL.
Version
This function is available since SDL 2.0.5.
