Wiki Page Content

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 length of a row of pixels in bytes

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) {
    SDL_Log("Loading image failed: %s", 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) {
    SDL_Log("Creating surface failed: %s", 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)

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