Source

pygame / docs / ref / surfarray.html

Full commit

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


<table cellspacing=3 width=100%><tr><td bgcolor=#00000>
<table width=100%><tr><td bgcolor=c2fc20 align=center>
    <a href=http://www.pygame.org>
    <img src=../pygame_tiny.gif border=0 width=200 height=60></a><br>
    <b>pygame&nbsp;&nbsp;&nbsp;documentation</b>
</td><td bgcolor=6aee28 align=center valign=top width=100%>

	||&nbsp;
	<a href=http://www.pygame.org>Pygame Home</a> &nbsp;||&nbsp;
	<a href=../index.html>Help Contents</a> &nbsp;||
	<a href=index.html>Reference Index</a> &nbsp;||
	<br>&nbsp;<br>
	
<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=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=pygame.html>Pygame</a>&nbsp;||&nbsp;
<a href=rect.html>Rect</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>
</p>


</td></tr></table></td></tr></table>
<br>


<a name="pygame.surfarray">
<big><b>pygame.surfarray</big></b><br><ul>
  <i>pygame module for accessing surface pixel data</i><br>
<ul><small><table>
  <tr><td><a href="surfarray.html#pygame.surfarray.array2d">pygame.surfarray.array2d</a></td><td>copy pixels into a 2d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.pixels2d">pygame.surfarray.pixels2d</a></td><td>reference pixels into a 2d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.array3d">pygame.surfarray.array3d</a></td><td>copy pixels into a 3d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.pixels3d">pygame.surfarray.pixels3d</a></td><td>reference pixels into a 3d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.array_alpha">pygame.surfarray.array_alpha</a></td><td>copy pixel alphas into a 2d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.pixels_alpha">pygame.surfarray.pixels_alpha</a></td><td>reference pixel alphas into a 2d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.array_colorkey">pygame.surfarray.array_colorkey</a></td><td>copy the colorkey values into a 2d array</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.make_surface">pygame.surfarray.make_surface</a></td><td>copy an array to a new surface</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.blit_array">pygame.surfarray.blit_array</a></td><td>blit directly from a array values</td></tr>
  <tr><td><a href="surfarray.html#pygame.surfarray.map_array">pygame.surfarray.map_array</a></td><td>map a 3d array into a 2d array</td></tr>
</table></small></ul>
<p>Functions to convert pixel data between pygame Surfaces and Numeric arrays. This module will only be available when pygame can use the external Numeric package. </p>
<p>Every pixel is stored as a single integer value to represent the red, green, and blue colors. The 8bit images use a value that looks into a colormap. Pixels with higher depth use a bit packing process to place three or four values into a single number. </p>
<p>The Numeric arrays are indexed by the <tt>X</tt> axis first, followed by the <tt>Y</tt> axis. Arrays that treat the pixels as a single integer are referred to as <tt>2D</tt> arrays. This module can also separate the red, green, and blue color values into separate indices. These types of arrays are referred to as <tt>3D</tt> arrays, and the last index is 0 for red, 1 for green, and 2 for blue. </p>
<p>Numeric does not use unsigned 16bit integers, images with 16bit data will be treated as signed integers. </p>
 &nbsp;<br> 


<a name="pygame.surfarray.array2d">
<big><b>pygame.surfarray.array2d</big></b><br><ul>
  <i>copy pixels into a 2d array</i><br>
  <tt>pygame.surfarray.array2d(Surface): return array</tt><br>
<p>Copy the pixels from a Surface into a <tt>2D</tt> array. The bit depth of the surface will control the size of the integer values, and will work for any type of pixel format. </p>
<p>This function will temporarily lock the Surface as pixels are copied (see the <tt><a href="surface.html#Surface.lock">Surface.lock</a></tt> method). </p>
 &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.pixels2d">
<big><b>pygame.surfarray.pixels2d</big></b><br><ul>
  <i>reference pixels into a 2d array</i><br>
  <tt>pygame.surfarray.pixels2d(Surface): return array</tt><br>
<p>Create a new <tt>2D</tt> array that directly references the pixel values in a Surface. Any changes to the array will affect the pixels in the Surface. This is a fast operation since no data is copied. </p>
<p>Pixels from a 24-bit Surface cannot be referenced, but all other Surface bit depths can. </p>
<p>The Surface this references will remain locked for the lifetime of the array (see the <tt><a href="surface.html#Surface.lock">Surface.lock</a></tt> method). </p>
 &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.array3d">
<big><b>pygame.surfarray.array3d</big></b><br><ul>
  <i>copy pixels into a 3d array</i><br>
  <tt>pygame.surfarray.array3d(Surface): return array</tt><br>
<p>Copy the pixels from a Surface into a <tt>3D</tt> array. The bit depth of the surface will control the size of the integer values, and will work for any type of pixel format. </p>
<p>This function will temporarily lock the Surface as pixels are copied (see the <tt><a href="surface.html#Surface.lock">Surface.lock</a></tt> method). </p>
 &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.pixels3d">
<big><b>pygame.surfarray.pixels3d</big></b><br><ul>
  <i>reference pixels into a 3d array</i><br>
  <tt>pygame.surfarray.pixels3d(Surface): return array</tt><br>
<p>Create a new <tt>3D</tt> array that directly references the pixel values in a Surface. Any changes to the array will affect the pixels in the Surface. This is a fast operation since no data is copied. </p>
<p>This will only work on Surfaces that have 24-bit or 32-bit formats. Lower pixel formats cannot be referenced. </p>
<p>The Surface this references will remain locked for the lifetime of the array (see the <tt><a href="surface.html#Surface.lock">Surface.lock</a></tt> method). </p>
 &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.array_alpha">
<big><b>pygame.surfarray.array_alpha</big></b><br><ul>
  <i>copy pixel alphas into a 2d array</i><br>
  <tt>pygame.surfarray.array_alpha(Surface): return array</tt><br>
<p>Copy the pixel alpha values (degree of transparency) from a Surface into a <tt>2D</tt> array. This will work for any type of Surface format. Surfaces without a pixel alpha will return an array with all opaque values. </p>
<p>This function will temporarily lock the Surface as pixels are copied (see the <tt><a href="surface.html#Surface.lock">Surface.lock</a></tt> method). </p>
 &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.pixels_alpha">
<big><b>pygame.surfarray.pixels_alpha</big></b><br><ul>
  <i>reference pixel alphas into a 2d array</i><br>
  <tt>pygame.surfarray.pixels_alpha(Surface): return array</tt><br>
<p>Create a new <tt>2D</tt> array that directly references the alpha values (degree of transparency) in a Surface. Any changes to the array will affect the pixels in the Surface. This is a fast operation since no data is copied. </p>
<p>This can only work on 32-bit Surfaces with a per-pixel alpha value. </p>
<p>The Surface this references will remain locked for the lifetime of the array. </p>
 &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.array_colorkey">
<big><b>pygame.surfarray.array_colorkey</big></b><br><ul>
  <i>copy the colorkey values into a 2d array</i><br>
  <tt>pygame.surfarray.array_colorkey(Surface): return array</tt><br>
<p>Create a new array with the colorkey transparency value from each pixel. If the pixel matches the colorkey it will be opaque, otherwise the value will be fully tranparent. </p>
<p>This will work on any type of Surface format. If the image has no colorkey a solid opaque array will be returned. </p>
<p>This function will temporarily lock the Surface as pixels are copied. </p>
 &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.make_surface">
<big><b>pygame.surfarray.make_surface</big></b><br><ul>
  <i>copy an array to a new surface</i><br>
  <tt>pygame.surfarray.make_surface(array): return Surface</tt><br>
<p>Create a new Surface that best resembles the data and format on the array. The array can be <tt>2D</tt> or <tt>3D</tt> with any sized integer values. </p>
 &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.blit_array">
<big><b>pygame.surfarray.blit_array</big></b><br><ul>
  <i>blit directly from a array values</i><br>
  <tt>pygame.surfarray.blit_array(Surface, array): return None</tt><br>
<p>Directly copy values from an array into a Surface. This is faster than converting the array into a Surface and blitting. The array must be the same dimensions as the Surface and will completely replace all pixel values. </p>
<p>This function will temporarily lock the Surface as the new values are copied. </p>
 &nbsp;<br> 
<br></ul>


<a name="pygame.surfarray.map_array">
<big><b>pygame.surfarray.map_array</big></b><br><ul>
  <i>map a 3d array into a 2d array</i><br>
  <tt>pygame.surfarray.map_array(Surface, array3d): return array2d</tt><br>
<p>Convert a <tt>3D</tt> array into a <tt>2D</tt> array. This will use the given Surface format to control the conversion. </p>
 &nbsp;<br> 
<br></ul>
<br></ul>

</body></html>