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