![]() pygame documentation |
||
Pygame Home ||
Help Contents ||
Reference Index ||
Cdrom || Cursors || Display || Draw || Event || Font || Image || Joystick || Key || Mask || Mixer || Mouse || Movie || Music || Overlay || Pixelarray || Pygame || Rect || Scrap || Sndarray || Sprite || Surface || Surfarray || Time || Transform |
PixelArray.surface - Gets the Surface the PixelArray uses. | Gets the Surface the PixelArray uses. |
NOTE: This is an EXPERIMENTAL class and subject to CHANGE in future versions.
The PixelArray wraps up a Surface and provides a direct 2D 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.
While it is possible to assign both, integer color values and RGB(A) color tuples, the PixelArray will only use integers for the color representation. Thus, checking for certain colors has to be done using the Surface.map_rgb - convert a color into a mapped color value method of the surface, the PixelArray was created for.
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)): ...
Pixels can be manipulated using integer values or color tuples.
pxarray[x][y] = 0xFF00FF pxarray[x][y] = (255, 0, 255)
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.
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
Note, that something like
pxarray[2:4][3:5] = ...
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:
pxarray[2][3:5] = ... pxarray[3][3:5] = ...
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.
New in pygame 1.8.
The Surface, the PixelArray was created for.