Wiki Page Content

Differences between revisions 4 and 5
Revision 4 as of 2016-10-16 01:46:43
Size: 3125
Editor: DanielG
Comment: add code example
Revision 5 as of 2016-10-16 01:52:30
Size: 3353
Editor: DanielG
Comment: add remark that pixel data is not copied and must be freed *after* freeing the surface
Deletions are marked like this. Additions are marked like this.
Line 88: Line 88:
## TODO: something about depth being 4 or 8 and palettes, like in SDL_CreateRGBSurface ?

No copy is made of the pixel data. Pixel data is not managed automatically; you must free the surface before you free the pixel data.

DRAFT

SDL_CreateRGBSurfaceWithFormatFrom

Use this function to allocate an RGB surface from provided pixel data.

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.

No copy is made of the pixel data. Pixel data is not managed automatically; you must free the surface before you free the pixel data.

Version

This function is available since SDL 2.0.5.


CategoryAPI, CategorySurface

None: SDL_CreateRGBSurfaceWithFormatFrom (last edited 2016-10-20 20:45:29 by PhilippWiesemann)

(Page Info.)
Feedback
Please include your contact information if you'd like to receive a reply.
Submit