misc/builddeps/win64/sdl/share/man/man3/SDL_LockSurface.3

   1 .TH "SDL_LockSurface" "3" "Tue 11 Sep 2001, 23:01" "SDL" "SDL API Reference"
   2 .SH "NAME"
   3 SDL_LockSurface \- Lock a surface for directly access\&.
   4 .SH "SYNOPSIS"
   5 .PP
   6 \fB#include "SDL\&.h"
   7 .sp
   8 \fBint \fBSDL_LockSurface\fP\fR(\fBSDL_Surface *surface\fR);
   9 .SH "DESCRIPTION"
  10 .PP
  11 \fBSDL_LockSurface\fP sets up a surface for directly accessing the pixels\&. Between calls to \fBSDL_LockSurface\fP and \fBSDL_UnlockSurface\fP, you can write to and read from \fBsurface->\fBpixels\fR\fR, using the pixel format stored in \fBsurface->\fBformat\fR\fR\&. Once you are done accessing the surface, you should use \fBSDL_UnlockSurface\fP to release it\&.
  12 .PP
  13 Not all surfaces require locking\&. If \fBSDL_MUSTLOCK\fP(\fBsurface\fR) evaluates to \fB0\fR, then you can read and write to the surface at any time, and the pixel format of the surface will not change\&.
  14 .PP
  15 No operating system or library calls should be made between lock/unlock pairs, as critical system locks may be held during this time\&.
  16 .PP
  17 It should be noted, that since SDL 1\&.1\&.8 surface locks are recursive\&. This means that you can lock a surface multiple times, but each lock must have a match unlock\&.
  18 .PP
  19 .nf
  20 \f(CW    \&.
  21     \&.
  22     SDL_LockSurface( surface );
  23     \&.
  24     /* Surface is locked */
  25     /* Direct pixel access on surface here */
  26     \&.
  27     SDL_LockSurface( surface );
  28     \&.
  29     /* More direct pixel access on surface */
  30     \&.
  31     SDL_UnlockSurface( surface );
  32     /* Surface is still locked */
  33     /* Note: Is versions < 1\&.1\&.8, the surface would have been */
  34     /* no longer locked at this stage                         */
  35     \&.
  36     SDL_UnlockSurface( surface );
  37     /* Surface is now unlocked */
  38     \&.
  39     \&.\fR
  40 .fi
  41 .PP
  42 .SH "RETURN VALUE"
  43 .PP
  44 \fBSDL_LockSurface\fP returns \fB0\fR, or \fB-1\fR if the surface couldn\&'t be locked\&.
  45 .SH "SEE ALSO"
  46 .PP
  47 \fI\fBSDL_UnlockSurface\fP\fR
  48 .\" created by instant / docbook-to-man, Tue 11 Sep 2001, 23:01