SDL_CreateRGBSurface(3)

💖 SDL_CreateRGBSurface 💖

okay so bestie, you want a brand new blank SDL_Surface? this is literally the function. it's part of the SDL API Reference, and honestly? it's giving arts-and-crafts day. 🎨✨

---

✨ NAME ✨

SDL_CreateRGBSurface — create an empty SDL_Surface 🫶

---

🌸 SYNOPSIS 🌸

#include "SDL.h"

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

like. eight arguments. she's high-maintenance but she's worth it. 💅

---

🦋 DESCRIPTION 🦋

So what she does is allocate an empty surface. and no cap, you must call this after SDL_SetVideoMode — that's not a vibe suggestion, that's a rule. 🚨

Now here's the tea about depth: if depth is 8 bits, an empty palette gets allocated for the surface. otherwise, a 'packed-pixel' SDL_PixelFormat is created using the [RGBA]mask's you provided (peep SDL_PixelFormat for the deets).

and the flags? that's you telling SDL what type of surface you want. it's an OR'd combination of these, so go wild (but responsibly): 💖

🎀 the flags, one by one 🎀

• SDL_SWSURFACE — SDL creates the surface in system memory. this is the one that makes pixel-level access faster, but the tradeoff is you might not get to take advantage of some types of hardware blitting. lowkey a fair trade, honestly.
• SDL_HWSURFACE — SDL attempts to create the surface in video memory. this lets SDL take advantage of Video->Video blits, which are often accelerated. go fast, queen. 🏎️
• SDL_SRCCOLORKEY — turns on colourkeying for blits from this surface. and if SDL_HWSURFACE is also specified and colourkeyed blits are hardware-accelerated, SDL will attempt to place the surface in video memory. use SDL_SetColorKey to set or clear this flag after surface creation. 👑
• SDL_SRCALPHA — turns on alpha-blending for blits from this surface. if SDL_HWSURFACE is also specified and alpha-blending blits are hardware-accelerated, then the surface will be placed in video memory if possible. use SDL_SetAlpha to set or clear this flag after surface creation. ✨

Note: if an alpha-channel is specified (that is, if Amask is nonzero), then the SDL_SRCALPHA flag is automatically set. not me getting a flag I didn't even ask for 😭 — but you may remove it by calling SDL_SetAlpha after surface creation. so it's fine, she's removable.

---

⭐ RETURN VALUE ⭐

Returns the created surface... or NULL upon error. 😭

like if you get NULL, something went wrong, bestie. don't just keep going — check it. 🙈

---

🌈 EXAMPLE 🌈

fr fr here's a whole 32-bit surface with the bytes of each pixel in R,G,B,A order, as expected by OpenGL for textures:

/* 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 *surface;
Uint32 rmask, gmask, bmask, amask;

/* SDL interprets each pixel as a 32-bit number, so our masks must depend
   on the endianness (byte order) of the machine */
#if SDL_BYTEORDER == SDL_BIG_ENDIAN
    rmask = 0xff000000;
    gmask = 0x00ff0000;
    bmask = 0x0000ff00;
    amask = 0x000000ff;
#else
    rmask = 0x000000ff;
    gmask = 0x0000ff00;
    bmask = 0x00ff0000;
    amask = 0xff000000;
#endif

surface = SDL_CreateRGBSurface(SDL_SWSURFACE, width, height, 32,
                               rmask, gmask, bmask, amask);
if(surface == NULL) {
    fprintf(stderr, "CreateRGBSurface failed: %s
", SDL_GetError());
    exit(1);
}

the way that endianness #if is essential — the masks literally depend on the byte order of the machine, so don't skip it. 🌸

---

💜 SEE ALSO 💜

• SDL_CreateRGBSurfaceFrom
• SDL_FreeSurface
• SDL_SetVideoMode
• SDL_LockSurface
• SDL_PixelFormat
• SDL_Surface
• SDL_SetAlpha
• SDL_SetColorKey

---

and that's the whole page, bestie. this one's from the SDL manual, dated Tue 11 Sep 2001, 23:01 — an actual icon of a timestamp, we love her. 💅✨ go make some surfaces. 🦋🎀