pygame / docs / ref / pixelarray.html

<title>pixelarray - Pygame Documentation</title>
<body bgcolor=#aaeebb text=#000000 link=#331111 vlink=#331111>

<table cellpadding=0 cellspacing=0 border=0 style='border: 3px solid black;' width='100%'>
<td bgcolor='#c2fc20' style='padding: 6px;' align=center valign=center><a href=''><img src='../pygame_tiny.gif' border=0 width=200 height=60></a><br><b>pygame documentation</b></td>
<td bgcolor='#6aee28' style='border-left: 3px solid black; padding: 6px;' align=center valign=center>
	<a href=>Pygame Home</a> &nbsp;||&nbsp;
	<a href=../index.html>Help Contents</a> &nbsp;||
	<a href=index.html>Reference Index</a> &nbsp;||
<a href=cdrom.html>Cdrom</a>&nbsp;||&nbsp;
<a href=cursors.html>Cursors</a>&nbsp;||&nbsp;
<a href=display.html>Display</a>&nbsp;||&nbsp;
<a href=draw.html>Draw</a>&nbsp;||&nbsp;
<a href=event.html>Event</a>&nbsp;||&nbsp;
<a href=font.html>Font</a>&nbsp;||&nbsp;
<a href=image.html>Image</a>&nbsp;||&nbsp;
<a href=joystick.html>Joystick</a>&nbsp;||&nbsp;
<a href=key.html>Key</a>&nbsp;||&nbsp;
<a href=mask.html>Mask</a>&nbsp;||&nbsp;
<a href=mixer.html>Mixer</a>&nbsp;||&nbsp;
<a href=mouse.html>Mouse</a>&nbsp;||&nbsp;
<a href=movie.html>Movie</a>&nbsp;||&nbsp;
<a href=music.html>Music</a>&nbsp;||&nbsp;
<a href=overlay.html>Overlay</a>&nbsp;||&nbsp;
<a href=pixelarray.html>Pixelarray</a>&nbsp;||&nbsp;
<a href=pygame.html>Pygame</a>&nbsp;||&nbsp;
<a href=rect.html>Rect</a>&nbsp;||&nbsp;
<a href=scrap.html>Scrap</a>&nbsp;||&nbsp;
<a href=sndarray.html>Sndarray</a>&nbsp;||&nbsp;
<a href=sprite.html>Sprite</a>&nbsp;||&nbsp;
<a href=surface.html>Surface</a>&nbsp;||&nbsp;
<a href=surfarray.html>Surfarray</a>&nbsp;||&nbsp;
<a href=time.html>Time</a>&nbsp;||&nbsp;
<a href=transform.html>Transform</a>

<a name="pygame.PixelArray">
  <i>pygame Object for direct pixel access of surfaces</i><br>
  <tt>pygame.PixelArray(Surface): return PixelArray</tt><br>
  <tr><td><a href="pixelarray.html#PixelArray.surface">PixelArray.surface</a> - <font size=-1>Gets the Surface the PixelArray uses.</font></td><td>Gets the Surface the PixelArray uses.</td></tr>
<p>The PixelArray wraps up a Surface and provides a direct <tt>2D</tt> array access to its pixels using the surface its rows as first and its columns as second axis. It supports slicing and row and pixel manipluation while inplace operations such as addition, subtraction, multiplication, division and slice assignments are not allowed. </p>
<p>While it is possible to assign both, integer color values and <tt>RGB(A)</tt> color tuples, the PixelArray will only use integers for the color representation. Thus, checking for certain colors has to be done using the <tt><a href="surface.html#Surface.map_rgb">Surface.map_rgb</a> - <font size=-1>convert a color into a mapped color value</font></tt> method of the surface, the PixelArray was created for. </p>
<pre>  pxarray = pygame.PixelArray (surface)
  # Check, if the first pixel at the topleft corner is blue
  if pxarray[0][0] == surface.map_rgb ((0, 0, 255)):
</pre><p>Pixels can be manipulated using integer values or color tuples. </p>
<pre>  pxarray[x][y] = 0xFF00FF
  pxarray[x][y] = (255, 0, 255)
</pre><p>If you operate on a slice, you also can use arbitrary sequences or other PixelArray objects to modify the pixels. They have to match the size of the PixelArray however. </p>
<pre>  pxarray[a:b] = 0xFF00FF                   # set all pixels to 0xFF00FF
  pxarray[a:b] = (0xFF00FF, 0xAACCEE, ... ) # first pixel = 0xFF00FF,
                                            # second pixel  = 0xAACCEE, ...
  pxarray[a:b] = ((255, 0, 255), (170, 204, 238), ...) # same as above
  pxarray[a:b] = ((255, 0, 255), 0xAACCEE, ...)        # same as above
  pxarray[a:b] = otherarray[x:y]            # slice sizes must match
</pre><p>Note, that something like </p>
<pre>  pxarray[2:4][3:5] = ...
</pre><p>will not cause a rectangular manipulation. Instead it will be first sliced to a two-column array, which then shall be sliced by columns once more, which will fail due an IndexError. This is caused by the slicing mechanisms in python and an absolutely correct behaviour. Create a single columned slice first, which you can manipulate then: </p>
<pre>  pxarray[2][3:5] = ...
  pxarray[3][3:5] = ...
</pre><p>During its lifetime, the PixelArray locks the surface, thus you explicitly have to delete it once its not used anymore and the surface should perform operations in the same scope. </p>
<p>New in pygame <tt>1.8</tt>. </p>
<!--COMMENTS:pygame.PixelArray--> &nbsp;<br> 

<a name="PixelArray.surface">
  <i>Gets the Surface the PixelArray uses.</i><br>
  <tt>PixelArray.surface: Return Surface</tt><br>
<p>The Surface, the PixelArray was created for. </p>
<!--COMMENTS:PixelArray.surface--> &nbsp;<br>