pygame documentation | || Home || Help Contents || || pygame || cdrom || constants || display || draw || event || || font || image || joystick || key || mixer || mixer_music || || mouse || movie || sndarray || surfarray || time || transform || || CD || Channel || Clock || Font || Joystick || Movie || || Rect || Sound || Surface || || color || cursors || sprite ||

## pygame.surfarray

Contains routines for mixing numeric arrays with surfaces. You can create arrays that directly reference the pixel data of an image. Sometimes this can be limited to the pixel format of the Surface, so you can also create independent copies from any format.
The image arrays are indexes 'X' axis first. This is different than traditional C memory access, where images are often indexed with the 'Y' axis first. All this means is to access pixel values in the array, you index them as 'X, Y' pairs. myarray[10,20] will provide you the pixel at 10, 20 in the image. If you prefer to work with the traditional framebuffer indices, use the arrays 'transpose()' method to create the alternate view of the pixel data.

array2d | - get a 2d array copied from a surface
array3d | - get a 3d array copied from a surface
array_alpha | - get an array with a surface pixel alpha values
array_colorkey | - get an array with a surface colorkey values
blit_array | - quickly transfer an array to a Surface
make_surface | - create a new Surface from array data
map_array | - map an array with RGB values into mapped colors
pixels2d | - get a 2d reference array to a surface
pixels3d | - get a 3d reference array to a surface
pixels_alpha | - get a reference array to a surface alpha data

array2d
`pygame.surfarray.array2d(Surface) -> Array`

This returns a new contigous 2d array. Think of it as a 2d image array with a mapped pixel value at each index.
This function will temporarily lock the surface.

array3d
`pygame.surfarray.array3d(Surface) -> Array`

This returns a new contigous 3d array. Think of it as a 2d image array with an RGB array for each pixel value.
This function will temporarily lock the surface.

array_alpha
`pygame.surfarray.array_alpha(Surface) -> Array`

This returns a new contigous 2d array with the alpha values of an image as unsigned bytes. If the surface has no alpha, an array of all opaque values is returned.
This function will temporarily lock the surface.

array_colorkey
`pygame.surfarray.array_colorkey(Surface) -> Array`

This returns a new contigous 2d array with the colorkey values of an image as unsigned bytes. If the surface has no colorkey, an array of all opaque values is returned. Otherwise the array is either 0's or 255's.
This function will temporarily lock the surface.

blit_array
`pygame.surfarray.blit_array(surf, array) -> None`

Transfer an array of any type (3d or 2d) onto a Surface. The array must be the same dimensions as the destination Surface. While you can assign the values of an array to the pixel referenced arrays, using this blit method will usually be quicker 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 internal conversions.
This function will temporarily lock the surface.

make_surface
`pygame.surfarray.make_surface(array) -> Surface`

Create a new software surface that closely resembles the data and format of the image array data.

map_array
`pygame.surfarray.map_array(surf, array3d) -> array2d`

Create a new array with the RGB pixel values of a 3d array into mapped color values in a 2D array.
Just so you know, this can also map a 2D array with RGB values into a 1D array of mapped color values

pixels2d
`pygame.surfarray.pixels2d(Surface) -> Array`

This returns a new noncontigous 2d array that directly effects a Surface's contents. Think of it as a 2d image array with a mapped pixel value at each index.
This will not work on 24bit surfaces, since there is no native 24bit data type to access the pixel values.
This function will lock the given surface, and it will remained locked for as long as the pixel array exists

pixels3d
`pygame.surfarray.pixels3d(Surface) -> Array`

This returns a new noncontigous 3d array that directly effects a Surface's contents. Think of it as a 2d image array with an RGB array for each pixel value.
This will only work for 24 and 32 bit surfaces, where the RGB components can be accessed as 8-bit components.
This function will lock the given surface, and it will remained locked for as long as the pixel array exists

pixels_alpha
`pygame.surfarray.pixels_alpha(Surface) -> Array`

This returns a new noncontigous array that directly effects a Surface's alpha contents.
This will only work for 32bit surfaces with a pixel alpha channel enabled.
This function will lock the given surface, and it will remained locked for as long as the pixel array exists