105 lines
4.4 KiB
Plaintext
105 lines
4.4 KiB
Plaintext
|
.. include:: common.txt
|
||
|
|
|
||
|
|
:mod:`pygame.pixelcopy`
|
||
|
|
=======================
|
||
|
|
|
||
|
|
.. module:: pygame.pixelcopy
|
||
|
|
:synopsis: pygame module for general pixel array copying
|
||
|
|
|
||
|
|
| :sl:`pygame module for general pixel array copying`
|
||
|
|
|
||
|
|
The ``pygame.pixelcopy`` module contains functions for copying between
|
||
|
|
surfaces and objects exporting an array structure interface. It is a backend
|
||
|
|
for :mod:`pygame.surfarray`, adding NumPy support. But pixelcopy is more
|
||
|
|
general, and intended for direct use.
|
||
|
|
|
||
|
|
The array struct interface exposes an array's data in a standard way.
|
||
|
|
It was introduced in NumPy. In Python 2.7 and above it is replaced by the
|
||
|
|
new buffer protocol, though the buffer protocol is still a work in progress.
|
||
|
|
The array struct interface, on the other hand, is stable and works with earlier
|
||
|
|
Python versions. So for now the array struct interface is the predominate way
|
||
|
|
pygame handles array introspection.
|
||
|
|
|
||
|
|
For 2d arrays of integer pixel values, the values are mapped to the
|
||
|
|
pixel format of the related surface. To get the actual color of a pixel
|
||
|
|
value use :meth:`pygame.Surface.unmap_rgb`. 2d arrays can only be used
|
||
|
|
directly between surfaces having the same pixel layout.
|
||
|
|
|
||
|
|
New in pygame 1.9.2.
|
||
|
|
|
||
|
|
.. function:: surface_to_array
|
||
|
|
|
||
|
|
| :sl:`copy surface pixels to an array object`
|
||
|
|
| :sg:`surface_to_array(array, surface, kind='P', opaque=255, clear=0) -> None`
|
||
|
|
|
||
|
|
The surface_to_array function copies pixels from a Surface object
|
||
|
|
to a 2D or 3D array. Depending on argument ``kind`` and the target array
|
||
|
|
dimension, a copy may be raw pixel value, RGB, a color component slice,
|
||
|
|
or colorkey alpha transparency value. Recognized ``kind`` values are the
|
||
|
|
single character codes 'P', 'R', 'G', 'B', 'A', and 'C'. Kind codes are case
|
||
|
|
insensitive, so 'p' is equivalent to 'P'. The first two dimensions
|
||
|
|
of the target must be the surface size (w, h).
|
||
|
|
|
||
|
|
The default 'P' kind code does a direct raw integer pixel (mapped) value
|
||
|
|
copy to a 2D array and a 'RGB' pixel component (unmapped) copy to a 3D array
|
||
|
|
having shape (w, h, 3). For an 8 bit colormap surface this means the
|
||
|
|
table index is copied to a 2D array, not the table value itself. A 2D
|
||
|
|
array's item size must be at least as large as the surface's pixel
|
||
|
|
byte size. The item size of a 3D array must be at least one byte.
|
||
|
|
|
||
|
|
For the 'R', 'G', 'B', and 'A' copy kinds a single color component
|
||
|
|
of the unmapped surface pixels are copied to the target 2D array.
|
||
|
|
For kind 'A' and surfaces with source alpha (the surface was created with
|
||
|
|
the SRCALPHA flag), has a colorkey
|
||
|
|
(set with :meth:`Surface.set_colorkey() <pygame.Surface.set_colorkey>`),
|
||
|
|
or has a blanket alpha
|
||
|
|
(set with :meth:`Surface.set_alpha() <pygame.Surface.set_alpha>`)
|
||
|
|
then the alpha values are those expected for a SDL surface.
|
||
|
|
If a surface has no explicit alpha value, then the target array
|
||
|
|
is filled with the value of the optional ``opaque`` surface_to_array
|
||
|
|
argument (default 255: not transparent).
|
||
|
|
|
||
|
|
Copy kind 'C' is a special case for alpha copy of a source surface
|
||
|
|
with colorkey. Unlike the 'A' color component copy, the ``clear``
|
||
|
|
argument value is used for colorkey matches, ``opaque`` otherwise.
|
||
|
|
By default, a match has alpha 0 (totally transparent), while everything
|
||
|
|
else is alpha 255 (totally opaque). It is a more general implementation
|
||
|
|
of :meth:`pygame.surfarray.array_colorkey`.
|
||
|
|
|
||
|
|
Specific to surface_to_array, a ValueError is raised for target arrays
|
||
|
|
with incorrect shape or item size. A TypeError is raised for an incorrect
|
||
|
|
kind code. Surface specific problems, such as locking, raise a pygame.error.
|
||
|
|
|
||
|
|
.. ## pygame.pixelcopy.surface_to_array ##
|
||
|
|
|
||
|
|
.. function:: array_to_surface
|
||
|
|
|
||
|
|
| :sl:`copy an array object to a surface`
|
||
|
|
| :sg:`array_to_surface(<surface>, <array>) -> None`
|
||
|
|
|
||
|
|
See :func:`pygame.surfarray.blit_array`.
|
||
|
|
|
||
|
|
.. ## pygame.pixelcopy.array_to_surface ##
|
||
|
|
|
||
|
|
.. function:: map_array
|
||
|
|
|
||
|
|
| :sl:`copy an array to another array, using surface format`
|
||
|
|
| :sg:`map_array(<array>, <array>, <surface>) -> None`
|
||
|
|
|
||
|
|
Map an array of color element values - (w, h, ..., 3) - to an array of
|
||
|
|
pixels - (w, h) according to the format of <surface>.
|
||
|
|
|
||
|
|
.. ## pygame.pixelcopy.map_array ##
|
||
|
|
|
||
|
|
.. function:: make_surface
|
||
|
|
|
||
|
|
| :sl:`Copy an array to a new surface`
|
||
|
|
| :sg:`pygame.pixelcopy.make_surface(array) -> Surface`
|
||
|
|
|
||
|
|
Create a new Surface that best resembles the data and format of the array.
|
||
|
|
The array can be 2D or 3D with any sized integer values.
|
||
|
|
|
||
|
|
.. ## pygame.pixelcopy.make_surface ##
|
||
|
|
|
||
|
|
.. ## pygame.pixelcopy ##
|