= SDL_Surface =
A structure that contains a collection of pixels used in software blitting.


== Data Fields ==
{|
|<span style="color: rgb(128, 128, 128);">Uint32</span>
|<span style="color: rgb(128, 128, 128);">'''flags'''</span>
|<span style="color: rgb(128, 128, 128);">(internal use)</span>
|-
|[[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) 
|-
|<span style="color: rgb(128, 128, 128);">int</span>
|<span style="color: rgb(128, 128, 128);">'''locked'''</span>
|<span style="color: rgb(128, 128, 128);">used for surfaces that require locking (internal use)</span>
|-
|<span style="color: rgb(128, 128, 128);">void*</span>
|<span style="color: rgb(128, 128, 128);">'''lock_data'''</span>
|<span style="color: rgb(128, 128, 128);">used for surfaces that require locking (internal use)</span>
|-
|[[SDL_Rect]] 
|'''clip_rect''' 
|an [[SDL_Rect]] structure used to clip blits to the surface which can be set by [[SDL_SetSurfaceClipRect]]() (read-only) 
|-
|<span style="color: rgb(128, 128, 128);">SDL_BlitMap*</span>
|<span style="color: rgb(128, 128, 128);">'''map'''</span>
|<span style="color: rgb(128, 128, 128);">info for fast blit mapping to other surfaces (internal use)</span>
|-
|int 
|'''refcount''' 
|reference count that can be incremented by the application 
|}


== Code Examples ==
<syntaxhighlight lang='c++'>
/* This is meant to show how to edit a surface's pixels on the CPU, but
   normally you should use SDL_FillSurfaceRect() 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);
}
</syntaxhighlight>

== Remarks ==
With most surfaces you can access the pixels directly.  Surfaces that have been optimized with [[SDL_SetSurfaceRLE]]() should be locked with [[SDL_LockSurface]]() before accessing '''pixels'''.  When you are done you should call [[SDL_UnlockSurface]]() before blitting.

== Related Functions ==
: [[SDL_BlitSurface]]
: [[SDL_ConvertSurface]]
: [[SDL_CreateRGBSurface]]
: [[SDL_CreateRGBSurfaceFrom]]
: [[SDL_FillSurfaceRect]]
: [[SDL_FillSurfaceRects]]
: [[SDL_DestroySurface]]
: [[SDL_GetSurfaceClipRect]]
: [[SDL_GetSurfaceColorKey]]
: [[SDL_GetSurfaceAlphaMod]]
: [[SDL_GetSurfaceBlendMode]]
: [[SDL_GetSurfaceColorMod]]
: [[SDL_LoadBMP_RW]]
: [[SDL_LockSurface]]
: [[SDL_BlitSurfaceUnchecked]]
: [[SDL_MUSTLOCK]]
: [[SDL_SaveBMP_RW]]
: [[SDL_SetSurfaceClipRect]]
: [[SDL_SetSurfaceColorKey]]
: [[SDL_SetSurfaceAlphaMod]]
: [[SDL_SetSurfaceBlendMode]]
: [[SDL_SetSurfaceColorMod]]
: [[SDL_SetSurfacePalette]]
: [[SDL_SetSurfaceRLE]]
: [[SDL_SoftStretch]]
: [[SDL_UnlockSurface]]

----
[[CategoryStruct]], [[CategorySurface]]