API Documentation

The main entrypoint for the library is the DispmanX class as described below.

DispmanX

DispmanX(
    layer: int = 0,
    display: Union[None, int, Display] = None,
    pixel_format: Literal["RGB", "ARGB", "RGBA", "RGBX", "XRGB", "RGBA16", "RGB565"] = "RGBA",
    buffer_type: Literal["auto", "numpy", "ctypes"] = "auto",
)

The DispmanX Class

You can use this class via the following,

from dispmanx import DispmanX

display = DispmanX()

Parameters:

Name	Type	Description	Default
layer	int	What layer to choose. For example, the default layer of Raspberry Pi OS Lite's terminal is -127, while omxplayer is 0.	0
display	Union[None, int, Display]	Which display to use. Choices: None — the default display as returned by get_default_display() An int device number of a specific display A Display object, for example, returned by list_displays())	None
pixel_format	Literal['RGB', 'ARGB', 'RGBA', 'RGBX', 'XRGB', 'RGBA16', 'RGB565']	Pixel format for the object. Choices: 'RGB' — 24-bit red, green, and blue 'ARGB' — 32-bit alpha, red, green, and blue 'RGBA' — 32-bit red, green, blue, and alpha 'RGBX' — 32-bit red, green, blue and an unused (X) byte 'XRGB' — 32-bit unused (X) byte, red, green, and blue 'RGBA16' — 16-bit red, green, blue and alpha packed as 4 bits per channel (represented as unsigned 16-bit integers when using NumPy) 'RGB565' — 16-bit red, green, blue packed as follows: 5 bits red, 6 bits green, 5 bits green (represented as unsigned 16-bit integers when using NumPy)	'RGBA'
buffer_type	Literal['auto', 'numpy', 'ctypes']	Type of buffer to write to the display from. Choices: 'auto' — defaults to a NumPy array if NumPy is available, otherwise a ctypes Array of c_char as described below 'numpy' — a NumPy array 'ctypes — a ctypes Array of c_char created with create_string_buffer()	'auto'

Raises:

Type	Description
DispmanXError	A user error occured by specifying an incorrect argument.
DispmanXRuntimeError	A serious error occured with the underlying DispmanX layer on your PI.

Attributes:

Name	Type	Description
buffer		A buffer representing underlying raw pixel data. It will be a NumPy array or ctypes Array of c_char depending on the value of the buffer_type argument.
buffer_type	str	Whether the buffer is a NumPy array or a ctypes Array. (Either "numpy" or "ctypes".)
display	Display	The display for which this object is attached to
pixel_format	str	The pixel format for this object. (One of "RGB", "ARGB", "RGBA", "RGBX", "XRGB", "RGBA16" or "RGB565".)
size	Size	The Size object representing the dimensions of the current display.
width	int	The width of the current display.
height	int	The height of the current display.
layer	int	The layer of this object.
destroyed	bool	Whether or not this object has been destroyed, is currently unusable, and no longer is available to display.

destroy

destroy() -> None

Destroy this DispmanX object

If the object is already destroyed, the operation will do nothing.

Raises:

Type	Description
DispmanXRuntimeError	Raised if there's an error destroying any of the underlying resources for the object

get_default_display classmethod

get_default_display() -> Display

Get the default Display.

This is both the first display returned by DispmanX layer, and the one used when creating DispmanX objects by default.

Returns:

Type	Description
Display	The default Display.

list_displays classmethod

list_displays() -> list[Display]

Get a list of available Displays.

Example

for display in DispmanX.list_display():
    print(f"{display.device_id}: {display.name}")

Returns:

Type	Description
list[Display]	List of available Displays.

Raises:

Type	Description
DispmanXRuntimeError	Raised if no devices are found, or there's an error while getting the list of displays.

update

update() -> None

Update the pixels based on what's in the buffer

Raises:

Type	Description
DispmanXRuntimeError	Raises if there's an error writing to the video memory

Other Classes

Display

Bases: NamedTuple

Returned by various interactions with the DispmanX class.

Not instantiated directly.

Attributes:

Name	Type	Description
device_id	int	The numeric ID associated with this display. You can use this to instantiate a DispmanX for this display.
name	str	The string representation of this display, for example "Main LCD", "HDMI 0", or "Composite" to name a few.
size	Size	The size of this display.

Size

Bases: NamedTuple

Returned by various interactions with the DismpanX and Display classes.

Not instantiated directly.

Attributes:

Name	Type	Description
width	int	The width component
height	int	The height component

Exceptions

DispmanXError

Bases: Exception

Raised when a recoverable error occurs with the underlying DispmanX library.

Likely a programmer error. You can try whatever you were doing again and correcting the offending behavior.

# Imported from dispmanx module
from dispmanx import DispmanXError

DispmanXRuntimeError

Bases: RuntimeError

Raised when an irrecoverable error occurs with the underlying DispmanX library.

Under normal circumstances, you should destroy any DispmanX objects you've instantiated when one of these exceptions gets raises. Or, your program should cleanly exit.

# Imported from dispmanx module
from dispmanx import DispmanXRuntimeError