Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Blame | Last modification | View Log | RSS feed

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