#pragma section-numbers off
#pragma camelcase off

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

<<TableOfContents()>>

== Data Fields ==
||<style="color: rgb(128, 128, 128);">Uint32 ||<style="color: rgb(128, 128, 128);">'''flags''' ||<style="color: rgb(128, 128, 128);">(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) ||
||<style="color: rgb(128, 128, 128);">int ||<style="color: rgb(128, 128, 128);">'''locked''' ||<style="color: rgb(128, 128, 128);">used for surfaces that require locking (internal use)||
||<style="color: rgb(128, 128, 128);">void* ||<style="color: rgb(128, 128, 128);">'''lock_data''' ||<style="color: rgb(128, 128, 128);">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) ||
||<style="color: rgb(128, 128, 128);">SDL_!BlitMap* ||<style="color: rgb(128, 128, 128);">'''map''' ||<style="color: rgb(128, 128, 128);">info for fast blit mapping to other surfaces (internal use)||
||int ||'''refcount''' ||reference count that can be incremented by the application ||


== Code Examples ==
{{{#!highlight cpp
/* 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);
}
}}}

== 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_FillRect]]
 . [[SDL_FillRects]]
 . [[SDL_FreeSurface]]
 . [[SDL_GetClipRect]]
 . [[SDL_GetColorKey]]
 . [[SDL_GetSurfaceAlphaMod]]
 . [[SDL_GetSurfaceBlendMode]]
 . [[SDL_GetSurfaceColorMod]]
 . [[SDL_LoadBMP_RW]]
 . [[SDL_LockSurface]]
 . [[SDL_LowerBlit]]
 . [[SDL_MUSTLOCK]]
 . [[SDL_SaveBMP_RW]]
 . [[SDL_SetClipRect]]
 . [[SDL_SetColorKey]]
 . [[SDL_SetSurfaceAlphaMod]]
 . [[SDL_SetSurfaceBlendMode]]
 . [[SDL_SetSurfaceColorMod]]
 . [[SDL_SetSurfacePalette]]
 . [[SDL_SetSurfaceRLE]]
 . [[SDL_SoftStretch]]
 . [[SDL_UnlockSurface]]

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