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 the numpy-based pixels2d() and pixels3d() 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 an arr[y][x] array, set the transpose argument to False.

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 of `arr[y][x]` axes. Defaults to `True`.
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.

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 an arr[y][x] array, set the transpose argument to False.

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 call numpy.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 of `arr[y][x]` axes. Defaults to `True`.
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.

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() or pixels3d() 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 call numpy.flip(arr, axis=2) to return a view of the array with the expected channel order.

Note

Unlike pixels2d() or pixels3d(), 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.

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() or pixels3d() to prevent it from being automatically freed during garbage collection. It should never be used for any other purpose.