Home | History | Annotate | Download | only in html 
      1 <HTML
      2 ><HEAD
      3 ><TITLE
      4 >SDL_LockSurface</TITLE
      5 ><META
      6 NAME="GENERATOR"
      7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
      8 "><LINK
      9 REL="HOME"
     10 TITLE="SDL Library Documentation"
     11 HREF="index.html"><LINK
     12 REL="UP"
     13 TITLE="Video"
     14 HREF="video.html"><LINK
     15 REL="PREVIOUS"
     16 TITLE="SDL_FreeSurface"
     17 HREF="sdlfreesurface.html"><LINK
     18 REL="NEXT"
     19 TITLE="SDL_UnlockSurface"
     20 HREF="sdlunlocksurface.html"></HEAD
     21 ><BODY
     22 CLASS="REFENTRY"
     23 BGCOLOR="#FFF8DC"
     24 TEXT="#000000"
     25 LINK="#0000ee"
     26 VLINK="#551a8b"
     27 ALINK="#ff0000"
     28 ><DIV
     29 CLASS="NAVHEADER"
     30 ><TABLE
     31 SUMMARY="Header navigation table"
     32 WIDTH="100%"
     33 BORDER="0"
     34 CELLPADDING="0"
     35 CELLSPACING="0"
     36 ><TR
     37 ><TH
     38 COLSPAN="3"
     39 ALIGN="center"
     40 >SDL Library Documentation</TH
     41 ></TR
     42 ><TR
     43 ><TD
     44 WIDTH="10%"
     45 ALIGN="left"
     46 VALIGN="bottom"
     47 ><A
     48 HREF="sdlfreesurface.html"
     49 ACCESSKEY="P"
     50 >Prev</A
     51 ></TD
     52 ><TD
     53 WIDTH="80%"
     54 ALIGN="center"
     55 VALIGN="bottom"
     56 ></TD
     57 ><TD
     58 WIDTH="10%"
     59 ALIGN="right"
     60 VALIGN="bottom"
     61 ><A
     62 HREF="sdlunlocksurface.html"
     63 ACCESSKEY="N"
     64 >Next</A
     65 ></TD
     66 ></TR
     67 ></TABLE
     68 ><HR
     69 ALIGN="LEFT"
     70 WIDTH="100%"></DIV
     71 ><H1
     72 ><A
     73 NAME="SDLLOCKSURFACE"
     74 ></A
     75 >SDL_LockSurface</H1
     76 ><DIV
     77 CLASS="REFNAMEDIV"
     78 ><A
     79 NAME="AEN1919"
     80 ></A
     81 ><H2
     82 >Name</H2
     83 >SDL_LockSurface&nbsp;--&nbsp;Lock a surface for directly access.</DIV
     84 ><DIV
     85 CLASS="REFSYNOPSISDIV"
     86 ><A
     87 NAME="AEN1922"
     88 ></A
     89 ><H2
     90 >Synopsis</H2
     91 ><DIV
     92 CLASS="FUNCSYNOPSIS"
     93 ><A
     94 NAME="AEN1923"
     95 ></A
     96 ><P
     97 ></P
     98 ><PRE
     99 CLASS="FUNCSYNOPSISINFO"
    100 >#include "SDL.h"</PRE
    101 ><P
    102 ><CODE
    103 ><CODE
    104 CLASS="FUNCDEF"
    105 >int <B
    106 CLASS="FSFUNC"
    107 >SDL_LockSurface</B
    108 ></CODE
    109 >(SDL_Surface *surface);</CODE
    110 ></P
    111 ><P
    112 ></P
    113 ></DIV
    114 ></DIV
    115 ><DIV
    116 CLASS="REFSECT1"
    117 ><A
    118 NAME="AEN1929"
    119 ></A
    120 ><H2
    121 >Description</H2
    122 ><P
    123 ><TT
    124 CLASS="FUNCTION"
    125 >SDL_LockSurface</TT
    126 > sets up a surface for directly 
    127 accessing the pixels.  Between calls to <TT
    128 CLASS="FUNCTION"
    129 >SDL_LockSurface</TT
    130 >
    131 and <TT
    132 CLASS="FUNCTION"
    133 >SDL_UnlockSurface</TT
    134 >, you can write to and read from 
    135 <TT
    136 CLASS="PARAMETER"
    137 ><I
    138 >surface-&#62;<TT
    139 CLASS="STRUCTFIELD"
    140 ><I
    141 >pixels</I
    142 ></TT
    143 ></I
    144 ></TT
    145 >, using the pixel format stored in
    146 <TT
    147 CLASS="PARAMETER"
    148 ><I
    149 >surface-&#62;<TT
    150 CLASS="STRUCTFIELD"
    151 ><I
    152 >format</I
    153 ></TT
    154 ></I
    155 ></TT
    156 >.  Once you are done accessing the
    157 surface, you should use <TT
    158 CLASS="FUNCTION"
    159 >SDL_UnlockSurface</TT
    160 > to release it.</P
    161 ><P
    162 >Not all surfaces require locking.  
    163 If <TT
    164 CLASS="LITERAL"
    165 >SDL_MUSTLOCK</TT
    166 >(<TT
    167 CLASS="PARAMETER"
    168 ><I
    169 >surface</I
    170 ></TT
    171 >)
    172 evaluates to <SPAN
    173 CLASS="RETURNVALUE"
    174 >0</SPAN
    175 >, then you can read and write to the 
    176 surface at any time, and the pixel format of the surface will not change. </P
    177 ><P
    178 >No operating system or library calls should be made between lock/unlock
    179 pairs, as critical system locks may be held during this time.</P
    180 ><P
    181 >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.
    182 <PRE
    183 CLASS="PROGRAMLISTING"
    184 >    .
    185     .
    186     SDL_LockSurface( surface );
    187     .
    188     /* Surface is locked */
    189     /* Direct pixel access on surface here */
    190     .
    191     SDL_LockSurface( surface );
    192     .
    193     /* More direct pixel access on surface */
    194     .
    195     SDL_UnlockSurface( surface );
    196     /* Surface is still locked */
    197     /* Note: Is versions &#60; 1.1.8, the surface would have been */
    198     /* no longer locked at this stage                         */
    199     .
    200     SDL_UnlockSurface( surface );
    201     /* Surface is now unlocked */
    202     .
    203     .</PRE
    204 ></P
    205 ></DIV
    206 ><DIV
    207 CLASS="REFSECT1"
    208 ><A
    209 NAME="AEN1947"
    210 ></A
    211 ><H2
    212 >Return Value</H2
    213 ><P
    214 ><TT
    215 CLASS="FUNCTION"
    216 >SDL_LockSurface</TT
    217 > returns <SPAN
    218 CLASS="RETURNVALUE"
    219 >0</SPAN
    220 >, 
    221 or <SPAN
    222 CLASS="RETURNVALUE"
    223 >-1</SPAN
    224 > if the surface couldn't be locked.</P
    225 ></DIV
    226 ><DIV
    227 CLASS="REFSECT1"
    228 ><A
    229 NAME="AEN1953"
    230 ></A
    231 ><H2
    232 >See Also</H2
    233 ><P
    234 ><A
    235 HREF="sdlunlocksurface.html"
    236 ><TT
    237 CLASS="FUNCTION"
    238 >SDL_UnlockSurface</TT
    239 ></A
    240 ></P
    241 ></DIV
    242 ><DIV
    243 CLASS="NAVFOOTER"
    244 ><HR
    245 ALIGN="LEFT"
    246 WIDTH="100%"><TABLE
    247 SUMMARY="Footer navigation table"
    248 WIDTH="100%"
    249 BORDER="0"
    250 CELLPADDING="0"
    251 CELLSPACING="0"
    252 ><TR
    253 ><TD
    254 WIDTH="33%"
    255 ALIGN="left"
    256 VALIGN="top"
    257 ><A
    258 HREF="sdlfreesurface.html"
    259 ACCESSKEY="P"
    260 >Prev</A
    261 ></TD
    262 ><TD
    263 WIDTH="34%"
    264 ALIGN="center"
    265 VALIGN="top"
    266 ><A
    267 HREF="index.html"
    268 ACCESSKEY="H"
    269 >Home</A
    270 ></TD
    271 ><TD
    272 WIDTH="33%"
    273 ALIGN="right"
    274 VALIGN="top"
    275 ><A
    276 HREF="sdlunlocksurface.html"
    277 ACCESSKEY="N"
    278 >Next</A
    279 ></TD
    280 ></TR
    281 ><TR
    282 ><TD
    283 WIDTH="33%"
    284 ALIGN="left"
    285 VALIGN="top"
    286 >SDL_FreeSurface</TD
    287 ><TD
    288 WIDTH="34%"
    289 ALIGN="center"
    290 VALIGN="top"
    291 ><A
    292 HREF="video.html"
    293 ACCESSKEY="U"
    294 >Up</A
    295 ></TD
    296 ><TD
    297 WIDTH="33%"
    298 ALIGN="right"
    299 VALIGN="top"
    300 >SDL_UnlockSurface</TD
    301 ></TR
    302 ></TABLE
    303 ></DIV
    304 ></BODY
    305 ></HTML
    306 >