====== (This is the documentation for SDL3, which is under heavy development and the API is changing! [https://wiki.libsdl.org/SDL2/ SDL2] is the current stable version!) ======
= SDL_LockSurface =

Set up a surface for directly accessing the pixels.

== Syntax ==

<syntaxhighlight lang='c'>
int SDL_LockSurface(SDL_Surface *surface);
</syntaxhighlight>

== 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.

== Remarks ==

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

Not all surfaces require locking. If <code>[[SDL_MUSTLOCK]](surface)</code>
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.

== Version ==

This function is available since SDL 3.0.0.

== Code Examples ==

<syntaxhighlight lang='c++'>
/* 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 */
</syntaxhighlight>

== Related Functions ==

:[[SDL_MUSTLOCK]]
:[[SDL_UnlockSurface]]

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