== Draft ==

'''THIS PAGE IS A WORK IN PROGRESS''' ... Please make edits to this page to improve it!


<!-- #*^*^*^*^*See https://wiki.libsdl.org/SGFunctions for details on editing this page*^*^*^*^* -->
= SDL_CreateRGBSurfaceWithFormat =

Allocate a new RGB surface with a specific pixel format.

== Syntax ==

<syntaxhighlight lang='c'>
SDL_Surface* SDL_CreateRGBSurfaceWithFormat
    (Uint32 flags, int width, int height, int depth, Uint32 format);
</syntaxhighlight>

== Function Parameters ==

{|
|'''flags'''
|the flags are unused and should be set to 0
|-
|'''width'''
|the width of the surface
|-
|'''height'''
|the height of the surface
|-
|'''depth'''
|the depth of the surface in bits
|-
|'''format'''
|the [[SDL_PixelFormatEnum]] for the new surface's pixel format.
|}

== Return Value ==

Returns the new [[SDL_Surface]] structure that is created or NULL if it
fails; call [[SDL_GetError]]() for more information.

== Remarks ==

This function operates mostly like [[SDL_CreateRGBSurface]](), except
instead of providing pixel color masks, you provide it with a predefined
format from [[SDL_PixelFormatEnum]].

== Version ==

This function is available since SDL 2.0.5.

== Code Examples ==

<syntaxhighlight lang='c++'>
    /* Create a 32-bit surface with the bytes of each pixel in R,G,B,A order,
       as expected by OpenGL for textures */

    SDL_Surface* surf;
    surf = SDL_CreateRGBSurfaceWithFormat(0, width, height, 32, SDL_PIXELFORMAT_RGBA32);
    if (surf == NULL) {
        SDL_Log("SDL_CreateRGBSurfaceWithFormat() failed: %s", SDL_GetError());
        exit(1);
    }
</syntaxhighlight>

== Related Functions ==

:[[SDL_CreateRGBSurface]]
:[[SDL_CreateRGBSurfaceFrom]]
:[[SDL_FreeSurface]]

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