Commits

Anonymous committed 4423986

locking doc updates

  • Participants
  • Parent commits 18d2a34

Comments (0)

Files changed (6)

File docs/ref/Surface.html

 doing of pixel work with them. If you plan on doing a lot of
 pixel level work, it is recommended to use the pygame.surfarray
 module, which can treat the surfaces like large multidimensional
-arrays (and it's quite quick). Some surfaces need to be locked
-before they can be used. Surfaces with flags like HWSURFACE and
-RLEACCEL generally require calls to <a href=#lock>lock()</a> and <a href=#unlock>unlock()</a>
-surrounding pixel access. It is safe to <a href=#lock>lock()</a> and <a href=#unlock>unlock()</a>
-surfaces that do not require locking. Nonetheless, you can check
-to see if a Surface really needs to be locked with the <a href=#mustlock>mustlock()</a>
-function.<p>&nbsp;</p>Here is the quick breakdown of how packed pixels work (don't worry if
+arrays (and it's quite quick).<p>&nbsp;</p>Any functions that directly access a surface's pixel data will
+need that surface to be <a href=#lock>lock()</a>'ed. These functions can <a href=#lock>lock()</a>
+and <a href=#unlock>unlock()</a> the surfaces themselves without assistance. But, if
+a function will be called many times, there will be a lot of overhead
+for multiple locking and unlocking of the surface. It is best to lock
+the surface manually before making the function call many times, and
+then unlocking when you are finished. All functions that need a locked
+surface will say so in their docs.
+<br>&nbsp;<br>
+Also remember that you will want to leave the surface locked for the
+shortest amount of time needed.
+<br>&nbsp;<br>
+<br>&nbsp;<br>
+Here is the quick breakdown of how packed pixels work (don't worry if
 you don't quite understand this, it is only here for informational
 purposes, it is not needed). Each colorplane mask can be used to
 isolate the values for a colorplane from the packed pixel color.
 color value bitwise left shifted a certain amount. The losses and
 masks can be used to convert back and forth between each
 colorplane and the actual color for that plane. Here are the
-final formulas used be map and unmap (not exactly, heh).
+final formulas used be map and unmap.
 PACKED_COLOR = RED&gt;&gt;losses[0]&lt;&lt;shifts[0] |
       GREEN&gt;&gt;losses[1]&lt;&lt;shifts[1] | BLUE&gt;&gt;losses[2]&lt;&lt;shifts[2]
 RED = PACKED_COLOR & masks[0] &gt;&gt; shifts[0] &lt;&lt; losses[0]
 query the surface height</td></tr>
 
 
+<tr><td><a href=#get_locked>get_locked</a></td><td> -
+check if the surface needs locking</td></tr>
+
+
 <tr><td><a href=#get_losses>get_losses</a></td><td> -
 get mapping losses for each colorplane</td></tr>
 
 Returns the RGB color values at a given pixel. If the
 Surface has no per-pixel alpha, the alpha will be 255 (opaque).
 <br>&nbsp;<br>
-Some surfaces will require the surface to be locked for pixel access.
-If locking is needed and the surface is not locked, it will be temporarily
-locked in this function. If you will be calling this function many times
-in one loop, it is will be much better to lock and unlock the surface
-outside of that loop.
+This function will temporarily lock the surface.
 </ul><br>&nbsp;<br>
 
 <a name=get_bitsize><font size=+2><b>get_bitsize
 Returns the height of the Surface.
 </ul><br>&nbsp;<br>
 
+<a name=get_locked><font size=+2><b>get_locked
+</b></font><br><font size=+1><tt>
+Surface.get_locked() -> bool
+</tt></font><ul>
+Returns true if the surface is currently locked.
+</ul><br>&nbsp;<br>
+
 <a name=get_losses><font size=+2><b>get_losses
 </b></font><br><font size=+1><tt>
 Surface.get_losses() -> redloss, greenloss, blueloss, alphaloss
 sized rectangle will be quicker. Also the fill function does not
 require the surface to be locked.
 <br>&nbsp;<br>
-Some surfaces will require the surface to be locked for pixel access.
-If locking is needed and the surface is not locked, it will be temporarily
-locked in this function. If you will be calling this function many times
-in one loop, it is will be much better to lock and unlock the surface
-outside of that loop.
+This function will temporarily lock the surface.
 </ul><br>&nbsp;<br>
 
 <a name=set_clip><font size=+2><b>set_clip
 Creates a new surface that shares pixel data of the given surface.
 Note that only the pixel data is shared. Things like clipping rectangles
 and colorkeys will be unique for the new surface.
-<br>&nbsp;<br>
-The fill is subject to be clipped by the active clipping
-rectangle. The return value contains the actual area filled.
 </ul><br>&nbsp;<br>
 
 <a name=unlock><font size=+2><b>unlock

File docs/ref/pygame_surfarray.html

 as a 2d image array with a mapped pixel value at
 each index.
 <br>&nbsp;<br>
-Some surfaces will require the surface to be locked for pixel access.
-If locking is needed and the surface is not locked, it will be temporarily
-locked in this function. If you will be calling this function many times
-in one loop, it is will be much better to lock and unlock the surface
-outside of that loop.
+This function will temporarily lock the surface.
 </ul><br>&nbsp;<br>
 
 <a name=array3d><font size=+2><b>array3d
 as a 2d image array with an RGB array for each
 pixel value.
 <br>&nbsp;<br>
-Some surfaces will require the surface to be locked for pixel access.
-If locking is needed and the surface is not locked, it will be temporarily
-locked in this function. If you will be calling this function many times
-in one loop, it is will be much better to lock and unlock the surface
-outside of that loop.
+This function will temporarily lock the surface.
 </ul><br>&nbsp;<br>
 
 <a name=array_alpha><font size=+2><b>array_alpha
 surface has no alpha, an array of all opaque values
 is returned.
 <br>&nbsp;<br>
-Some surfaces will require the surface to be locked for pixel access.
-If locking is needed and the surface is not locked, it will be temporarily
-locked in this function. If you will be calling this function many times
-in one loop, it is will be much better to lock and unlock the surface
-outside of that loop.
+This function will temporarily lock the surface.
 </ul><br>&nbsp;<br>
 
 <a name=array_colorkey><font size=+2><b>array_colorkey
 surface has no colorkey, an array of all opaque values
 is returned. Otherwise the array is either 0's or 255's.
 <br>&nbsp;<br>
-Some surfaces will require the surface to be locked for pixel access.
-If locking is needed and the surface is not locked, it will be temporarily
-locked in this function. If you will be calling this function many times
-in one loop, it is will be much better to lock and unlock the surface
-outside of that loop.
+This function will temporarily lock the surface.
 </ul><br>&nbsp;<br>
 
 <a name=blit_array><font size=+2><b>blit_array
 because of it's smarter handling of noncontiguous
 arrays. Plus it allows you to blit from any image
 array type to any surface format in one step, no
-conversions.
+internal conversions.
 <br>&nbsp;<br>
-Some surfaces will require the surface to be locked for pixel access.
-If locking is needed and the surface is not locked, it will be temporarily
-locked in this function. If you will be calling this function many times
-in one loop, it is will be much better to lock and unlock the surface
-outside of that loop.
+This function will temporarily lock the surface.
 </ul><br>&nbsp;<br>
 
 <a name=map_array><font size=+2><b>map_array
 is no native 24bit data type to access the pixel
 values.
 <br>&nbsp;<br>
-You'll need the surface to be locked if that is
-required. Also be aware that between unlocking and
-relocking a surface, the pixel data can be moved,
-so don't hang onto this array after you have
-unlocked the surface.
+This function will lock the given surface, and it
+will remained locked for as long as the pixel array
+exists
 </ul><br>&nbsp;<br>
 
 <a name=pixels3d><font size=+2><b>pixels3d
 pixel value.
 <br>&nbsp;<br>
 This will only work for 24 and 32 bit surfaces,
-where the RGB components can be accessed without
-requiring any masking.
+where the RGB components can be accessed as 8-bit
+components.
 <br>&nbsp;<br>
-You'll need the surface to be locked if that is
-required. Also be aware that between unlocking and
-relocking a surface, the pixel data can be moved,
-so don't hang onto this array after you have
-unlocked the surface.
+This function will lock the given surface, and it
+will remained locked for as long as the pixel array
+exists
 </ul><br>&nbsp;<br>
 
 <a name=pixels_alpha><font size=+2><b>pixels_alpha
 This will only work for 32bit surfaces with a pixel
 alpha channel enabled.
 <br>&nbsp;<br>
-You'll need the surface to be locked if that is
-required. Also be aware that between unlocking and
-relocking a surface, the pixel data can be moved,
-so don't hang onto this array after you have
-unlocked the surface.
+This function will lock the given surface, and it
+will remained locked for as long as the pixel array
+exists
 </ul><br>&nbsp;<br>
 
 
     /*DOC*/    "rectangle. A bounding box of the effected area is returned\n"
     /*DOC*/    "as a rectangle.\n"
     /*DOC*/    "\n"
+    /*DOC*/    "This function will temporarily lock the surface.\n"
     /*DOC*/ ;
 
 static PyObject* line(PyObject* self, PyObject* arg)

File src/surface.c

     /*DOC*/    "Returns the RGB color values at a given pixel. If the\n"
     /*DOC*/    "Surface has no per-pixel alpha, the alpha will be 255 (opaque).\n"
     /*DOC*/    "\n"
-    /*DOC*/    "Some surfaces will require the surface to be locked for pixel access.\n"
-    /*DOC*/    "If locking is needed and the surface is not locked, it will be temporarily\n"
-    /*DOC*/    "locked in this function. If you will be calling this function many times\n"
-    /*DOC*/    "in one loop, it is will be much better to lock and unlock the surface\n"
-    /*DOC*/    "outside of that loop.\n"
+    /*DOC*/    "This function will temporarily lock the surface.\n"
     /*DOC*/ ;
 
 static PyObject* surf_get_at(PyObject* self, PyObject* arg)
     /*DOC*/    "sized rectangle will be quicker. Also the fill function does not\n"
     /*DOC*/    "require the surface to be locked.\n"
     /*DOC*/    "\n"
-    /*DOC*/    "Some surfaces will require the surface to be locked for pixel access.\n"
-    /*DOC*/    "If locking is needed and the surface is not locked, it will be temporarily\n"
-    /*DOC*/    "locked in this function. If you will be calling this function many times\n"
-    /*DOC*/    "in one loop, it is will be much better to lock and unlock the surface\n"
-    /*DOC*/    "outside of that loop.\n"
+    /*DOC*/    "This function will temporarily lock the surface.\n"
     /*DOC*/ ;
 
 static PyObject* surf_set_at(PyObject* self, PyObject* args)
     /*DOC*/    "doing of pixel work with them. If you plan on doing a lot of\n"
     /*DOC*/    "pixel level work, it is recommended to use the pygame.surfarray\n"
     /*DOC*/    "module, which can treat the surfaces like large multidimensional\n"
-    /*DOC*/    "arrays (and it's quite quick). Some surfaces need to be locked\n"
-    /*DOC*/    "before they can be used. Surfaces with flags like HWSURFACE and\n"
-    /*DOC*/    "RLEACCEL generally require calls to lock() and unlock()\n"
-    /*DOC*/    "surrounding pixel access. It is safe to lock() and unlock()\n"
-    /*DOC*/    "surfaces that do not require locking. Nonetheless, you can check\n"
-    /*DOC*/    "to see if a Surface really needs to be locked with the mustlock()\n"
-    /*DOC*/    "function.\n"
+    /*DOC*/    "arrays (and it's quite quick).\n"
     /*DOC*/ ;
 
 

File src/surfarray.c

     /*DOC*/    "pixel value.\n"
     /*DOC*/    "\n"
     /*DOC*/    "This will only work for 24 and 32 bit surfaces,\n"
-    /*DOC*/    "where the RGB components can be accessed without\n"
-    /*DOC*/    "requiring any masking.\n"
+    /*DOC*/    "where the RGB components can be accessed as 8-bit\n"
+    /*DOC*/    "components.\n"
     /*DOC*/    "\n"
-    /*DOC*/    "You'll need the surface to be locked if that is\n"
-    /*DOC*/    "required. Also be aware that between unlocking and\n"
-    /*DOC*/    "relocking a surface, the pixel data can be moved,\n"
-    /*DOC*/    "so don't hang onto this array after you have\n"
-    /*DOC*/    "unlocked the surface.\n"
+    /*DOC*/    "This function will lock the given surface, and it\n"
+    /*DOC*/    "will remained locked for as long as the pixel array\n"
+    /*DOC*/    "exists\n"
     /*DOC*/ ;
 
 static PyObject* pixels3d(PyObject* self, PyObject* arg)
     /*DOC*/    "is no native 24bit data type to access the pixel\n"
     /*DOC*/    "values.\n"
     /*DOC*/    "\n"
-    /*DOC*/    "You'll need the surface to be locked if that is\n"
-    /*DOC*/    "required. Also be aware that between unlocking and\n"
-    /*DOC*/    "relocking a surface, the pixel data can be moved,\n"
-    /*DOC*/    "so don't hang onto this array after you have\n"
-    /*DOC*/    "unlocked the surface.\n"
+    /*DOC*/    "This function will lock the given surface, and it\n"
+    /*DOC*/    "will remained locked for as long as the pixel array\n"
+    /*DOC*/    "exists\n"
     /*DOC*/ ;
 
 static PyObject* pixels2d(PyObject* self, PyObject* arg)
     /*DOC*/    "This will only work for 32bit surfaces with a pixel\n"
     /*DOC*/    "alpha channel enabled.\n"
     /*DOC*/    "\n"
-    /*DOC*/    "You'll need the surface to be locked if that is\n"
-    /*DOC*/    "required. Also be aware that between unlocking and\n"
-    /*DOC*/    "relocking a surface, the pixel data can be moved,\n"
-    /*DOC*/    "so don't hang onto this array after you have\n"
-    /*DOC*/    "unlocked the surface.\n"
+    /*DOC*/    "This function will lock the given surface, and it\n"
+    /*DOC*/    "will remained locked for as long as the pixel array\n"
+    /*DOC*/    "exists\n"
     /*DOC*/ ;
 
 static PyObject* pixels_alpha(PyObject* self, PyObject* arg)
     /*DOC*/    "as a 2d image array with a mapped pixel value at\n"
     /*DOC*/    "each index.\n"
     /*DOC*/    "\n"
-    /*DOC*/    "Some surfaces will require the surface to be locked for pixel access.\n"
-    /*DOC*/    "If locking is needed and the surface is not locked, it will be temporarily\n"
-    /*DOC*/    "locked in this function. If you will be calling this function many times\n"
-    /*DOC*/    "in one loop, it is will be much better to lock and unlock the surface\n"
-    /*DOC*/    "outside of that loop.\n"
+    /*DOC*/    "This function will temporarily lock the surface.\n"
     /*DOC*/ ;
 
 PyObject* array2d(PyObject* self, PyObject* arg)
     /*DOC*/    "as a 2d image array with an RGB array for each\n"
     /*DOC*/    "pixel value.\n"
     /*DOC*/    "\n"
-    /*DOC*/    "Some surfaces will require the surface to be locked for pixel access.\n"
-    /*DOC*/    "If locking is needed and the surface is not locked, it will be temporarily\n"
-    /*DOC*/    "locked in this function. If you will be calling this function many times\n"
-    /*DOC*/    "in one loop, it is will be much better to lock and unlock the surface\n"
-    /*DOC*/    "outside of that loop.\n"
+    /*DOC*/    "This function will temporarily lock the surface.\n"
     /*DOC*/ ;
 
 PyObject* array3d(PyObject* self, PyObject* arg)
     /*DOC*/    "surface has no alpha, an array of all opaque values\n"
     /*DOC*/    "is returned.\n"
     /*DOC*/    "\n"
-    /*DOC*/    "Some surfaces will require the surface to be locked for pixel access.\n"
-    /*DOC*/    "If locking is needed and the surface is not locked, it will be temporarily\n"
-    /*DOC*/    "locked in this function. If you will be calling this function many times\n"
-    /*DOC*/    "in one loop, it is will be much better to lock and unlock the surface\n"
-    /*DOC*/    "outside of that loop.\n"
+    /*DOC*/    "This function will temporarily lock the surface.\n"
     /*DOC*/ ;
 
 PyObject* array_alpha(PyObject* self, PyObject* arg)
     /*DOC*/    "surface has no colorkey, an array of all opaque values\n"
     /*DOC*/    "is returned. Otherwise the array is either 0's or 255's.\n"
     /*DOC*/    "\n"
-    /*DOC*/    "Some surfaces will require the surface to be locked for pixel access.\n"
-    /*DOC*/    "If locking is needed and the surface is not locked, it will be temporarily\n"
-    /*DOC*/    "locked in this function. If you will be calling this function many times\n"
-    /*DOC*/    "in one loop, it is will be much better to lock and unlock the surface\n"
-    /*DOC*/    "outside of that loop.\n"
+    /*DOC*/    "This function will temporarily lock the surface.\n"
     /*DOC*/ ;
 
 PyObject* array_colorkey(PyObject* self, PyObject* arg)
     /*DOC*/    "because of it's smarter handling of noncontiguous\n"
     /*DOC*/    "arrays. Plus it allows you to blit from any image\n"
     /*DOC*/    "array type to any surface format in one step, no\n"
-    /*DOC*/    "conversions.\n"
+    /*DOC*/    "internal conversions.\n"
     /*DOC*/    "\n"
-    /*DOC*/    "Some surfaces will require the surface to be locked for pixel access.\n"
-    /*DOC*/    "If locking is needed and the surface is not locked, it will be temporarily\n"
-    /*DOC*/    "locked in this function. If you will be calling this function many times\n"
-    /*DOC*/    "in one loop, it is will be much better to lock and unlock the surface\n"
-    /*DOC*/    "outside of that loop.\n"
+    /*DOC*/    "This function will temporarily lock the surface.\n"
     /*DOC*/ ;
 
 PyObject* blit_array(PyObject* self, PyObject* arg)

File src/surflock.c

 /*extra Surface documentation*/
 #if 0 /*extra help, only for docs, not docstrings*/
     /*DOC*/ static char doc_Surface_EXTRA[] =
+    /*DOC*/    "Any functions that directly access a surface's pixel data will\n"
+    /*DOC*/    "need that surface to be lock()'ed. These functions can lock()\n"
+    /*DOC*/    "and unlock() the surfaces themselves without assistance. But, if\n"
+    /*DOC*/    "a function will be called many times, there will be a lot of overhead\n"
+    /*DOC*/    "for multiple locking and unlocking of the surface. It is best to lock\n"
+    /*DOC*/    "the surface manually before making the function call many times, and\n"
+    /*DOC*/    "then unlocking when you are finished. All functions that need a locked\n"
+    /*DOC*/    "surface will say so in their docs.\n"
+    /*DOC*/    "\n"
+    /*DOC*/    "Also remember that you will want to leave the surface locked for the\n"
+    /*DOC*/    "shortest amount of time needed.\n"
+    /*DOC*/    "\n"
+    /*DOC*/    "\n"
     /*DOC*/    "Here is the quick breakdown of how packed pixels work (don't worry if\n"
     /*DOC*/    "you don't quite understand this, it is only here for informational\n"
     /*DOC*/    "purposes, it is not needed). Each colorplane mask can be used to\n"