Contains routines for mixing numeric arrays with surfaces


  • pygame.surfarray.pixels3d(Surface) -> Array
  • - get a 3d reference array to a surface
  • pygame.surfarray.pixels2d(Surface) -> Array
  • - get a 2d reference array to a surface
  • pygame.surfarray.array2d(Surface) -> Array
  • - get a 2d array copied from a surface
  • pygame.surfarray.array3d(Surface) -> Array
  • - get a 3d array copied from a surface
  • map_array(surf, array3d) -> array2d
  • - map_array(surf, array1d) -> array1d
  • blit_array(surf, array) -> None
  • - quickly transfer an array to a Surface


    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 without requiring any masking. 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.


    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. 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.


    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. You'll need the surface to be locked if that is required. Once the array is created you can unlock the surface.


    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. You'll need the surface to be locked if that is required. Once the array is created you can unlock the surface.


    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


    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 conversions.