#pragma section-numbers off
#pragma disable-camelcase

= SDL_LockSurface =
Use this function to set up a surface for directly accessing the pixels.

<<TableOfContents()>>

== Syntax ==
{{{#!highlight cpp
int SDL_LockSurface(SDL_Surface* surface)
}}}

== Function Parameters ==
||'''surface'''||the [[SDL_Surface]] structure to be locked||

== Return Value ==
Returns 0 on success or a negative error code on failure; call [[SDL_GetError]]() for more information.

== Code Examples ==
{{{#!highlight cpp
/* Make the pixels pointer valid in the surface */

SDL_LockSurface(surface);

/* Surface is locked */
/* Direct pixel access on surface here */

SDL_UnlockSurface(surface);

/* Surface is now unlocked */
}}}


== Remarks ==
Between calls to [[SDL_LockSurface]]() / [[SDL_UnlockSurface]](), you can write to and read from `surface->pixels`, using the pixel format stored in `surface->format`. Once you are done accessing the surface, you should use [[SDL_UnlockSurface]]() to release it.

Not all surfaces require locking. If [[SDL_MUSTLOCK]](surface) evaluates to 0, then you can read and write to the surface at any time, and the pixel format of the surface will not change.

== Related Functions ==
 .[[SDL_MUSTLOCK]]
 .[[SDL_UnlockSurface]]

----
[[CategoryAPI]], [[CategorySurface]]