sdl2.ext.pixelaccess - Array-like Access to SDL Surface Contents¶
The sdl2.ext.pixelaccess
module offers a number of methods for reading,
modifying, and copying the contents SDL surface objects.
In most cases, the Numpy-based pixels2d()
,
pixels3d()
, and surface_to_ndarray()
functions
are the fastest and most flexible way of directly accessing the pixels of an
SDL surface. However, the pure-Python PixelView
class can
be used instead to avoid adding Numpy as a dependency for your project.
-
class
sdl2.ext.pixelaccess.
PixelView
(source)[source]¶ A 2D memory view for reading and writing SDL surface pixels.
This class uses a
view[y][x]
layout, with the y-axis as the first dimension and the x-axis as the second.PixelView
objects currently do not support array slicing, but support negative indexing as of PySDL2 0.9.10.If the source surface is RLE-accelerated, it will be locked automatically when the view is created and you will need to re-lock the surface using
SDL_UnlockSurface()
once you are done with the view.Warning
The source surface should not be freed or deleted until the view is no longer needed. Accessing the view for a freed surface will likely cause Python to hard-crash.
Note
This class is implemented on top of the
MemoryView
class. As such, it makes heavy use of recursion to access rows and will generally be much slower than thenumpy
-basedpixels2d()
andpixels3d()
functions.Parameters: source ( SDL_Surface
,SoftwareSprite
) – The SDL surface to access with the view.
-
sdl2.ext.pixelaccess.
pixels2d
(source, transpose=True)[source]¶ Creates a 2D Numpy array view for a given SDL surface.
This function casts the surface pixels to a 2D Numpy array view, providing read and write access to the underlying surface. If the source surface is RLE-accelerated, it will be locked automatically when the view is created and you will need to re-lock the surface using
SDL_UnlockSurface()
once you are done with the array.By default, the array is returned in
arr[x][y]
format with the x-axis as the first dimension, contrary to PIL and PyOpenGL convention. To obtain anarr[y][x]
array, set thetranspose
argument toFalse
.Warning
The source surface should not be freed or deleted until the array is no longer needed. Accessing the array for a freed surface will likely cause Python to hard-crash.
Note
This function requires Numpy to be installed in the current Python environment.
Parameters: - source (
SDL_Surface
,SoftwareSprite
) – The SDL surface to cast to a numpy array. - transpose (bool, optional) – Whether the output array should be
transposed to have
arr[x][y]
axes instead ofarr[y][x]
axes. Defaults toTrue
.
Returns: A 2-dimensional Numpy array containing the integer color values for each pixel in the surface.
Return type: numpy.ndarray
Raises: RuntimeError
– If Numpy could not be imported.- source (
-
sdl2.ext.pixelaccess.
pixels3d
(source, transpose=True)[source]¶ Creates a 3D Numpy array view for a given SDL surface.
This function casts the surface pixels to a 3D Numpy array view, providing read and write access to the underlying surface. If the source surface is RLE-accelerated, it will be locked automatically when the view is created and you will need to re-lock the surface using
SDL_UnlockSurface()
once you are done with the array.By default, the array is returned in
arr[x][y]
format with the x-axis as the first dimension, contrary to PIL and PyOpenGL convention. To obtain anarr[y][x]
array, set thetranspose
argument toFalse
.When creating a 3D array view, the order of the RGBA values for each pixel may be reversed for some common surface pixel formats (e.g. ‘BGRA’ for a
SDL_PIXELFORMAT_ARGB8888
surface). To correct this, you can callnumpy.flip(arr, axis=2)
to return a view of the array with the expected channel order.Warning
The source surface should not be freed or deleted until the array is no longer needed. Accessing the array for a freed surface will likely cause Python to hard-crash.
Note
This function requires Numpy to be installed in the current Python environment.
Parameters: - source (
SDL_Surface
,SoftwareSprite
) – The SDL surface to cast to a numpy array. - transpose (bool, optional) – Whether the output array should be
transposed to have
arr[x][y]
axes instead ofarr[y][x]
axes. Defaults toTrue
.
Returns: A 3-dimensional Numpy array containing the values of each byte for each pixel in the surface.
Return type: numpy.ndarray
Raises: RuntimeError
– If Numpy could not be imported.- source (
-
sdl2.ext.pixelaccess.
surface_to_ndarray
(source, ndim=3)[source]¶ Returns a copy of an SDL surface as a Numpy array.
The main difference between this function and
pixels2d()
orpixels3d()
is that it returns a copy of the surface instead of a view, meaning that modifying the returned array will not affect the original surface (or vice-versa). This function is also slightly safer, as it does not assume that the source surface has been kept in memory.When creating a 3D array copy, the order of the RGBA values for each pixel may be reversed for some common surface pixel formats (e.g. ‘BGRA’ for a
SDL_PIXELFORMAT_ARGB8888
surface). To correct this, you can callnumpy.flip(arr, axis=2)
to return a view of the array with the expected channel order.Note
Unlike
pixels2d()
orpixels3d()
, this function always returns arrays with the y-axis as the first dimension (e.g.arr[y][x]
).Note
This function requires Numpy to be installed in the current Python environment.
Parameters: - source (
SDL_Surface
,SoftwareSprite
) – The SDL surface to convert to a numpy array. - ndim (int, optional) – The number of dimensions for the returned array, must be either 2 (for a 2D array) or 3 (for a 3D array). Defaults to 3.
Returns: A Numpy array containing a copy of the pixel data for the given surface.
Return type: numpy.ndarray
Raises: RuntimeError
– If Numpy could not be imported.- source (
-
class
sdl2.ext.pixelaccess.
SurfaceArray
[source]¶ A Numpy array that keeps a reference to its parent SDL surface.
This class is used to keep track of the original source object for
pixels2d()
orpixels3d()
to prevent it from being automatically freed during garbage collection. It should never be used for any other purpose.