SDL_CreateSurfaceFrom(3)

📦
version 3.4.18 · 9 versions
, in fedora 43, fedora 44

💖 SDL_CreateSurfaceFrom(3) 💖

okay bestie, so this is a page from the SDL3 FUNCTIONS manual, and today's main character is SDL_CreateSurfaceFrom — the function that hands you a brand-new surface built around pixel data you already have. no copy, no drama, just vibes 🦋

✨ NAME ✨

SDL_CreateSurfaceFrom — allocate a new surface with a specific pixel format and existing pixel data. it's giving "i brought my own pixels, you bring the surface" 💅

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_surface.h>

SDL_Surface * SDL_CreateSurfaceFrom(int width, int height, SDL_PixelFormat format, void *pixels, int pitch);

🎀 DESCRIPTION 🎀

okay so here's the tea, and it's important tea: no copy is made of the pixel data. like, none. zero. the surface just points at your pixels. which means the pixel data is not managed automatically — you have to free the surface before you free the pixel data. do it in that order, bestie, or you're gonna have a bad time 😭

pitch is the offset in bytes from one row of pixels to the next. so like, width*4 for SDL_PIXELFORMAT_RGBA8888. that's the math, no cap 🧮

and the fun part: you may pass NULL for pixels and 0 for pitch to create a surface that you'll fill in with valid values later. build-a-bear but for surfaces, lowkey iconic 🧸

🫶 FUNCTION PARAMETERS 🫶

  • width — the width of the surface. yeah. that one. 📏
  • height — the height of the surface. the other one. 📐
  • format — the SDL_PixelFormat for the new surface's pixel format. pick your aesthetic ✨
  • pixels — a pointer to existing pixel data. your pixels. your problem (affectionately) 💜
  • pitch — the number of bytes between each row, including padding. padding is real and it counts 🎀

⭐ RETURN VALUE ⭐

returns the new SDL_Surface structure that is created, or NULL on failure. if you get NULL, don't panic — just call SDL_GetError() for more information and it'll spill the whole story 💀

🔥 THREAD SAFETY 🔥

it is safe to call this function from any thread. yes, any thread. multitask slay 👑

🌈 AVAILABILITY 🌈

this function is available since SDL 3.2.0. if your SDL is older than that, it's simply not invited to the party 🙈

💖 SEE ALSO 💖

and that's the whole page, bestie — go forth and make surfaces 🦋

with love from the Simple Directmedia Layer girlies, SDL 3.4.18 era, SDL_CreateSurfaceFrom(3) forever 💅✨

📦 where this page comes from