SDL_Surface(3type)

💖 SDL_Surface — bestie, it's the pixel girly 💖

okay so you know how a manual page header is like a little name tag? this one says SDL_Surface(3type) and it lives in the SDL3 DATATYPES section, and honestly? she's the blueprint. the moment. the canvas. periodt. 💅

✨ NAME ✨

SDL_Surface — a collection of pixels used in software blitting.

no cap, that's it. a whole vibe made of pixels. 🎀

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_surface.h>

struct SDL_Surface
{
    SDL_SurfaceFlags flags;     /**< The flags of the surface, read-only */
    SDL_PixelFormat format;     /**< The format of the surface, read-only */
    int w;                      /**< The width of the surface, read-only. */
    int h;                      /**< The height of the surface, read-only. */
    int pitch;                  /**< The distance in bytes between rows of pixels, read-only */
    void *pixels;               /**< A pointer to the pixels of the surface, the pixels are writeable if non-NULL */

    int refcount;               /**< Application reference count, used when freeing surface */

    void *reserved;             /**< Reserved for internal use */
};

look at her. an icon. 👑

🦋 DESCRIPTION 🦋

okay so the pixels are laid out in memory in rows, and the top row comes first. very top-down, very organized, we respect it. each row takes up an amount of memory given by the pitch (which, in non-SDL APIs, people sometimes call the row stride — same thing, different name, iykyk).

inside each row, the pixels go left to right until you hit the w (width). each pixel eats up however many bits its format says it should, and for most formats that's one or more whole bytes per pixel — except in some indexed formats, where instead multiple pixels get packed into each single byte (sneaky!! 🙈), plus a byte order that the format dictates. once all the pixels are encoded, whatever bytes are left over to reach the pitch are just padding to hit a desired alignment, and those contents are undefined. so like, don't read them, bestie. undefined means undefined. 💀

when a surface is holding YUV format data, the planes are assumed to be contiguous with no padding between them. example, since examples are everything: a 32x32 surface in NV12 format with a pitch of 32 would be 32x32 bytes of Y plane followed by 32x16 bytes of UV plane. math-ing. 🔥

and when a surface is holding MJPG format data? then pixels points at the compressed JPEG image, and pitch is the length of that data. compressed girlies stay compressed. ✨

🌈 AVAILABILITY 🌈

this struct has been available since SDL 3.2.0. she's not new new, but she's not ancient either. 🫶

⭐ SEE ALSO ⭐

• SDL_CreateSurface(3) — go make one 💖
• SDL_DestroySurface(3) — and go free her when you're done, we do not leak in this house 😭

---

heads up bestie: reserved is for internal use only, so like. hands off. 🙈

okay that's the whole page, you ate, I ate, we all ate. this was the Simple Directmedia Layer manual, SDL 3.4.18 era, page SDL_Surface(3type) — mwah, go blit something cute. 💜🧚🌸