SDL_Surface(3)

💖 SDL_Surface(3) 💖

okay so bestie, you've stumbled into the SDL API Reference and this is the page about surfaces — the single most important lil struct in all of SDL graphics. buckle up, hydrate, and let's go 🌸

---

✨ NAME ✨

SDL_Surface — Graphical Surface Structure 🎨

---

🎀 STRUCTURE DEFINITION 🎀

here's the whole vibe, laid out exactly how it lives in the header, no cap:

typedef struct SDL_Surface {
        Uint32 flags;                           /* Read-only */
        SDL_PixelFormat *format;                /* Read-only */
        int w, h;                               /* Read-only */
        Uint16 pitch;                           /* Read-only */
        void *pixels;                           /* Read-write */

        /* clipping information */
        SDL_Rect clip_rect;                     /* Read-only */

        /* Reference count -- used when freeing surface */
        int refcount;                           /* Read-mostly */

     /* This structure also contains private fields not shown here */
} SDL_Surface;

👀 notice the comments on each field, they tell you what you're allowed to touch. read them. respect them.

---

🦋 STRUCTURE DATA 🦋

• flags — the surface flags, aka the whole personality of your surface 🚩
• format — the pixel format
• w, h — width and height of the surface 📐
• pitch — length of a surface scanline, in bytes
• pixels — pointer to the actual pixel data, the real MVP 💅
• clip_rect — the surface clip rectangle ✂️

---

🌈 DESCRIPTION 🌈

SDL_Surface's represent areas of "graphical" memory — memory that can be drawn to. that's literally the whole point of them, they're canvases you can paint on 💖

the video framebuffer is returned as a SDL_Surface by SDL_SetVideoMode and SDL_GetVideoSurface. so yes, your whole screen is lowkey just a surface. main character energy fr.

most of the fields should be pretty obvious. w and h are the width and height of the surface in pixels. pixels is a pointer to the actual pixel data, and — listen — the surface should be locked before accessing this field. do not skip that step, i'm begging 🫠

the clip_rect field is the clipping rectangle as set by SDL_SetClipRect.

---

🌟 the flags field 🌟

the following are supported in the flags field. there's a lot of them, and each one is a whole mood:

• SDL_SWSURFACE — surface is stored in system memory 🧠
• SDL_HWSURFACE — surface is stored in video memory 🎮
• SDL_ASYNCBLIT — surface uses asynchronous blits if possible ⚡
• SDL_ANYFORMAT — allows any pixel-format (Display surface) 🌈
• SDL_HWPALETTE — surface has exclusive palette 🎨
• SDL_DOUBLEBUF — surface is double buffered (Display surface) 🪞
• SDL_FULLSCREEN — surface is full screen (Display Surface) 🖥️
• SDL_OPENGL — surface has an OpenGL context (Display Surface) 🔺
• SDL_OPENGLBLIT — surface supports OpenGL blitting (Display Surface) ✨
• SDL_RESIZABLE — surface is resizable (Display Surface) ↔️
• SDL_HWACCEL — surface blit uses hardware acceleration 🏎️
• SDL_SRCCOLORKEY — surface use colorkey blitting 🔑
• SDL_RLEACCEL — colorkey blitting is accelerated with RLE 💨
• SDL_SRCALPHA — surface blit uses alpha blending 🫥
• SDL_PREALLOC — surface uses preallocated memory 📦

several of these are tagged (Display surface) or (Display Surface) — that's not decoration, that's telling you they only apply to the display surface, iykyk 👑

---

👀 SEE ALSO 👀

• SDL_PixelFormat

---

and that's the page, bestie!! you ate that 💅 this was the SDL_Surface(3) page from the SDL API Reference, dated Tue 11 Sep 2001, 23:01 — yes, an absolute icon from an absolute era, we stan a vintage queen 👑🫶 mwah, go lock your surface before you touch pixels, love u bye 🎀💖✨