• SDL_LockSurface

SDL_LockSurface function

SDL_LockSurface -- Locks a surface for direct pixel access

Syntax

int SDL_LockSurface(SDL_Surface* surface);

Description

SDL_LockSurface sets up a surface for directly accessing the pixels. Between calls to SDL_LockSurface and 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 the lock.

Not all surfaces require locking. If SDL_MUSTLOCK(surface) evaluates to 0, then reading and writing pixels to the surface can be performed at any time, and the pixel format of the surface will not change.

No operating system or library calls should be made between the lock/unlock pairs, as critical system locks may be held during this time.

Note : Since SDL 1.1.8, the surface locks are recursive. This means that you can lock a surface multiple times, but each lock must have a matching unlock.

Parameter

surface [in]

• The pointer to the surface to lock

Return value

-1

• On error

0

• On success

See also

SDL_UnlockSurface

Example

   1 SDL_Surface* surface = NULL;
   2 
   3 /* Assign a surface pointer to surface */
   4 
   5 SDL_LockSurface( surface );
   6 
   7 /* Surface is locked */
   8 /* Direct pixel access on surface here */
   9 
  10 SDL_LockSurface( surface );
  11 
  12 /* More direct pixel access on surface */
  13 
  14 SDL_UnlockSurface( surface );
  15 
  16 /* Surface is still locked */
  17 /* Note: In versions < 1.1.8, the surface would have been */
  18 /* no longer locked at this stage                         */
  19 
  20 SDL_UnlockSurface( surface );
  21 /* Surface is now unlocked */
  22 
  23 SDL_FreeSurface( surface );
  24 surface = NULL;

Requirements

CategorySDLVideo