home *** CD-ROM | disk | FTP | other *** search
/ RISCWORLD 7 / RISCWORLD_VOL7.iso / Software / Issue4 / SDL / gcc346 / !SDL / man / SDL_LockSurface.3 < prev    next >
Encoding:
Text File  |  2006-09-20  |  2.6 KB  |  80 lines
  1. <!-- manual page source format generated by PolyglotMan v3.0.8+X.Org, -->
  2. <!-- available at http://polyglotman.sourceforge.net/ -->
  3.  
  4. <html>
  5. <head>
  6. <title>"SDL_LockSurface"("3") manual page</title>
  7. </head>
  8. <body bgcolor='#efefef' text='black' link='blue' vlink='#551A8B' alink='red'>
  9. <a href='#toc'>Table of Contents</a><p>
  10.  
  11. <h2><a name='sect0' href='#toc0'>Name</a></h2>
  12. SDL_LockSurface- Lock a surface for directly access. 
  13. <h2><a name='sect1' href='#toc1'>Synopsis</a></h2>
  14. <p>
  15. <b>#include
  16. "SDL.h" <p>
  17. </b><b>int <b>SDL_LockSurface</b></b>(<b>SDL_Surface *surface</b>); 
  18. <h2><a name='sect2' href='#toc2'>Description</a></h2>
  19. <p>
  20. <b>SDL_LockSurface</b>
  21. sets up a surface for directly accessing the pixels. Between calls to <b>SDL_LockSurface</b>
  22. and <b>SDL_UnlockSurface</b>, you can write to and read from <b>surface-><b>pixels</b></b>, using
  23. the pixel format stored in <b>surface-><b>format</b></b>. Once you are done accessing the
  24. surface, you should use <b>SDL_UnlockSurface</b> to release it. <p>
  25. Not all surfaces
  26. require locking. If <b>SDL_MUSTLOCK</b>(<b>surface</b>) evaluates to <b>0</b>, then you can read
  27. and write to the surface at any time, and the pixel format of the surface
  28. will not change.  <p>
  29. No operating system or library calls should be made between
  30. lock/unlock pairs, as critical system locks may be held during this time.
  31. <p>
  32. It should be noted, that since SDL 1.1.8 surface locks are recursive. This
  33. means that you can lock a surface multiple times, but each lock must have
  34. a match unlock.  <p>
  35. <br>
  36. <pre>CW    .
  37.     .
  38.     SDL_LockSurface( surface );
  39.     .
  40.     /* Surface is locked */
  41.     /* Direct pixel access on surface here */
  42.     .
  43.     SDL_LockSurface( surface );
  44.     .
  45.     /* More direct pixel access on surface */
  46.     .
  47.     SDL_UnlockSurface( surface );
  48.     /* Surface is still locked */
  49.     /* Note: Is versions < 1.1.8, the surface would have been */
  50.     /* no longer locked at this stage                         */
  51.     .
  52.     SDL_UnlockSurface( surface );
  53.     /* Surface is now unlocked */
  54.     .
  55.     .
  56. </pre><p>
  57.  
  58. <h2><a name='sect3' href='#toc3'>Return Value</a></h2>
  59. <p>
  60. <b>SDL_LockSurface</b> returns <b>0</b>, or <b>-1</b> if the surface couldn't be locked.
  61.  
  62. <h2><a name='sect4' href='#toc4'>See Also</a></h2>
  63. <p>
  64. <i><b>SDL_UnlockSurface</b></i> 
  65. <!--
  66.   
  67.  <p>
  68.  
  69. <hr><p>
  70. <a name='toc'><b>Table of Contents</b></a><p>
  71. <ul>
  72. <li><a name='toc0' href='#sect0'>Name</a></li>
  73. <li><a name='toc1' href='#sect1'>Synopsis</a></li>
  74. <li><a name='toc2' href='#sect2'>Description</a></li>
  75. <li><a name='toc3' href='#sect3'>Return Value</a></li>
  76. <li><a name='toc4' href='#sect4'>See Also</a></li>
  77. </ul>
  78. </body>
  79. </html>
  80.