====== (This is the legacy documentation for stable SDL2, the current stable version; [https://wiki.libsdl.org/SDL3/ SDL3] is the current development version.) ======
= SDL_Surface =
A collection of pixels used in software blitting.
== Header File ==
Defined in [SDL_surface.h](https://github.com/libsdl-org/SDL/blob/SDL2/include/SDL_surface.h), but apps should _only_ `#include "SDL.h"`!
== Syntax ==
typedef struct SDL_Surface
{
Uint32 flags; /**< Read-only */
SDL_PixelFormat *format; /**< Read-only */
int w, h; /**< Read-only */
int pitch; /**< Read-only */
void *pixels; /**< Read-write */
/** Application data associated with the surface */
void *userdata; /**< Read-write */
/** information needed for surfaces requiring locks */
int locked; /**< Read-only */
/** list of BlitMap that hold a reference to this surface */
void *list_blitmap; /**< Private */
/** clipping information */
SDL_Rect clip_rect; /**< Read-only */
/** info for fast blit mapping to other surfaces */
SDL_BlitMap *map; /**< Private */
/** Reference count -- used when freeing surface */
int refcount; /**< Read-mostly */
} SDL_Surface;
== Code Examples ==
/* This is meant to show how to edit a surface's pixels on the CPU, but
normally you should use SDL_FillRect() to wipe a surface's contents. */
void WipeSurface(SDL_Surface *surface)
{
/* This is fast for surfaces that don't require locking. */
/* Once locked, surface->pixels is safe to access. */
SDL_LockSurface(surface);
/* This assumes that color value zero is black. Use
SDL_MapRGBA() for more robust surface color mapping! */
/* height times pitch is the size of the surface's whole buffer. */
SDL_memset(surface->pixels, 0, surface->h * surface->pitch);
SDL_UnlockSurface(surface);
}
== Data Fields ==
{|
|Uint32
|'''flags'''
|(internal use)
|-
|[[SDL_PixelFormat]]*
|'''format'''
|the format of the pixels stored in the surface; see [[SDL_PixelFormat]] for details (read-only)
|-
|int
|'''w, h'''
|the width and height in pixels (read-only)
|-
|int
|'''pitch'''
|the length of a row of pixels in bytes (read-only)
|-
|void*
|'''pixels'''
|the pointer to the actual pixel data; see [[#Remarks|Remarks]] for details (read-write)
|-
|void*
|'''userdata'''
|an arbitrary pointer you can set (read-write)
|-
|int
|'''locked'''
|used for surfaces that require locking (internal use)
|-
|void*
|'''lock_data'''
|used for surfaces that require locking (internal use)
|-
|[[SDL_Rect]]
|'''clip_rect'''
|an [[SDL_Rect]] structure used to clip blits to the surface which can be set by [[SDL_SetClipRect]]() (read-only)
|-
|SDL_BlitMap*
|'''map'''
|info for fast blit mapping to other surfaces (internal use)
|-
|int
|'''refcount'''
|reference count that can be incremented by the application
|}
----
[[CategoryAPI]], [[CategoryAPIStruct]], [[CategoryStruct]], [[CategorySurface]]