###### (This is the legacy documentation for SDL2, the previous stable version; [SDL3](https://wiki.libsdl.org/SDL3/) is the current stable version.)
# SDL_CreateRGBSurface

Allocate a new RGB surface.

## Header File

Defined in [SDL_surface.h](https://github.com/libsdl-org/SDL/blob/SDL2/include/SDL_surface.h)

## Syntax

```c
SDL_Surface* SDL_CreateRGBSurface
    (Uint32 flags, int width, int height, int depth,
     Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
```

## Function Parameters

|                  |            |                                              |
| ---------------- | ---------- | -------------------------------------------- |
| [Uint32](Uint32) | **flags**  | the flags are unused and should be set to 0. |
| int              | **width**  | the width of the surface.                    |
| int              | **height** | the height of the surface.                   |
| int              | **depth**  | the depth of the surface in bits.            |
| [Uint32](Uint32) | **Rmask**  | the red mask for the pixels.                 |
| [Uint32](Uint32) | **Gmask**  | the green mask for the pixels.               |
| [Uint32](Uint32) | **Bmask**  | the blue mask for the pixels.                |
| [Uint32](Uint32) | **Amask**  | the alpha mask for the pixels.               |

## Return Value

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

## Remarks

If `depth` is 4 or 8 bits, an empty palette is allocated for the surface.
If `depth` is greater than 8 bits, the pixel format is set using the
[RGBA]mask parameters.

The [RGBA]mask parameters are the bitmasks used to extract that color from
a pixel. For instance, `Rmask` being 0xFF000000 means the red data is
stored in the most significant byte. Using zeros for the RGB masks sets a
default value, based on the depth. For example:

```c++
SDL_CreateRGBSurface(0,w,h,32,0,0,0,0);
```

However, using zero for the Amask results in an Amask of 0.

By default surfaces with an alpha mask are set up for blending as with:

```c++
SDL_SetSurfaceBlendMode(surface, SDL_BLENDMODE_BLEND)
```

You can change this by calling
[SDL_SetSurfaceBlendMode](SDL_SetSurfaceBlendMode)() and selecting a
different `blendMode`.

## Version

This function is available since SDL 2.0.0.

## See Also

- [SDL_CreateRGBSurfaceFrom](SDL_CreateRGBSurfaceFrom)
- [SDL_CreateRGBSurfaceWithFormat](SDL_CreateRGBSurfaceWithFormat)
- [SDL_FreeSurface](SDL_FreeSurface)

----
[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategorySurface](CategorySurface)