#pragma section-numbers off
#pragma camelcase off
||<tablewidth="100%" style="color: #FF0000;" :> DRAFT||

##*^*^*^*^*See http://wiki.libsdl.org/moin.cgi/SGFunctions for details on editing this page*^*^*^*^*


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


<<TableOfContents()>>


== Syntax ==
{{{#!highlight cpp
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 [[SDL_PixelFormatEnum|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 ==
{{{#!highlight cpp
// 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.

## 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.

== Version ==
This function is available since SDL 2.0.5.


== Related Functions ==
 .[[SDL_CreateRGBSurfaceFrom]]
 .[[SDL_CreateRGBSurfaceWithFormat]]
 .[[SDL_FreeSurface]]
##Remove this section if empty

----
[[CategoryAPI]], [[CategorySurface]]
##See the Style Guide for instructions on editing the footer.