libretro.drivers.video.driver¶

Types and classes for defining how a core renders graphics.

Classes

`FrameBufferSpecial`	Sentinel return values from `VideoDriver.refresh()` that aren't ordinary frame buffers.
`Screenshot`	A snapshot of the most recently rendered video frame.
`VideoDriver`	Describes functionality for rendering video output, including essential libretro callbacks and environment calls.

Exceptions

UnsupportedContextError

Raised when a core requests a graphics context that a VideoDriver doesn't support.

class VideoDriver[source]¶

Bases: Protocol

Describes functionality for rendering video output, including essential libretro callbacks and environment calls.

Some of these may not be implemented by all drivers.

abstractmethod refresh(data, width, height, pitch)[source]¶

Update the framebuffer with the given video data. This method is exposed to the core through retro_set_video_refresh.

Parameters:

data (memoryview[int] | FrameBufferSpecial) –
One of the following:

memoryview
Contains pixel data in the format given by pixel_format. Should be read-only.

FrameBufferSpecial.DUPE
If the frontend should re-render the previous frame.

FrameBufferSpecial.HARDWARE
If the frontend should render the frame using the active graphics API context.
width (int) – The width of the frame in data, in pixels.
height (int) – The height of the frame in data, in pixels.
pitch (int) – The width of the frame in data, in bytes.

Raises:

TypeError – If any parameter’s type is not consistent with this method’s signature.
ValueError – If data is a memoryview and its length is not equal to pitch * height.

Return type:

None

Note

Corresponds to retro_video_refresh_t.

abstract property needs_reinit¶: True if this video driver needs to be reinitialized, usually because of core-requested state changes. Can also indicate that the driver hasn’t yet been initialized at all.

Warning

VideoDriver implementations aren’t necessarily initialized in their constructors.

abstractmethod reinit()[source]¶

Reinitializes the video driver, applying any changes made to it since the last call to this method.

The video driver will perform the following steps:

Call the registered retro_hw_render_callback.context_destroy (if any) to tell the core to release any resources associated with the current graphics API.
Release all libretro.py-managed graphics resources.
Release the graphics context if switching to a different graphics API or making changes that require a new context.
Initialize a new graphics context if necessary.
Initialize internal resources for libretro.py.
Call the registered retro_hw_render_callback.context_reset (if any) to tell the core it can initialize its graphics API resources.

Tip

The purpose of retro_hw_render_callback.cache_context is to tell libretro.py to do its best to avoid calling this method.

Return type:: None

abstract property supported_contexts¶: The set of all graphics APIs supported by this driver. All video drivers must support at least HardwareContext.NONE, which indicates software rendering capabilities.

Tip

Most drivers won’t support more than one kind of graphics context (not counting NONE), but this isn’t a hard requirement.

abstract property active_context¶

The hardware context that is currently exposed to the core. Must be an element of supported_contexts.

Will be HardwareContext.NONE until the core successfully requests a graphics context using EnvironmentCall.SET_HW_RENDER, at which point it will be set to the requested context type.

Attention

This property does not necessarily indicate which graphics API is loaded and active; it specifically means the context type that the core requested.

For example, a core that uses software rendering wouldn’t request a hardware context, therefore this property would return HardwareContext.NONE regardless of the actual graphics API in use.

After all, most of RetroArch’s video drivers rely on hardware graphics APIs, even if the core doesn’t request them. If the core is only software-rendered, then what difference does it make?

abstract property preferred_context¶

The preferred hardware context for this driver. Cores that support multiple graphics APIs can use this to choose one without the player needing to specify it.

Can be a member of supported_contexts (including NONE) to indicate preference for that context, or None to disable EnvironmentCall.GET_PREFERRED_HW_RENDER.

Setting or deleting this property will not affect the active context.

Raises:

ValueError – If attempting to set a preferred context that this driver doesn’t support (i.e. that’s not in supported_contexts).
TypeError – If attempting to set a value that isn’t a HardwareContext.

Note

Corresponds to RETRO_ENVIRONMENT_GET_PREFERRED_HW_RENDER.

abstractmethod set_context(callback)[source]¶

Request the use of a particular graphics context, including HardwareContext.NONE to revert to software rendering. The driver won’t be reinitialized until the next call to reinit().

Parameters:

callback (retro_hw_render_callback) – A retro_hw_render_callback with the context parameters requested by the core, plus callbacks to run at certain points in the context’s lifecycle.

Raises:

TypeError – If callback is not a retro_hw_render_callback.
UnsupportedContextError – If the driver cannot set the requested context with the requested parameters.

Return type:

None

Note

Corresponds to RETRO_ENVIRONMENT_SET_HW_RENDER.

Note

There’s no need to set the callbacks; this is done by the EnvironmentDriver.

abstract property current_framebuffer¶

The current framebuffer for the active graphics context. The core should use this framebuffer when rendering to the screen. Software-rendered graphics will be drawn to this framebuffer.

Returns:: An integer identifier for the current framebuffer, or None if the driver doesn’t support or need this feature.

Note

Corresponds to retro_hw_render_callback.get_current_framebuffer.

This property is generally only used by OpenGL and OpenGL ES, but it’s part of the general retro_hw_render_callback structure for historical reasons.

abstractmethod get_proc_address(sym)[source]¶

Return the address of the graphics API function with the given name.

Parameters:: sym (bytes) – The name of the function to look up.
Return type:: CFunctionType | None
Returns:: The address of the function if found, None otherwise. Will also return None if the driver doesn’t support or need this feature.
Raises:: TypeError – If sym is not a bytes.

Note

Corresponds to retro_hw_render_callback.get_proc_address.

This property is generally only used by OpenGL and OpenGL ES, but it’s part of the general retro_hw_render_callback structure for historical reasons.

abstract property rotation¶

The angle by which the output should be rotated, in increments of 90 degrees.

If the video driver doesn’t support rotation, then this property will always return Rotation.NONE.

Raises:: NotImplementedError – If setting or deleting this property on a VideoDriver that doesn’t support doing so.

Note

Corresponds to RETRO_ENVIRONMENT_SET_ROTATION.

abstract property can_dupe¶

Whether the frontend can re-render the previous frame.

True if frame duping is supported, False if not.

If None, then RETRO_ENVIRONMENT_GET_CAN_DUPE is unavailable to cores.

Raises:: NotImplementedError – If setting or deleting this property on a VideoDriver that doesn’t support doing so.

Note

Corresponds to RETRO_ENVIRONMENT_GET_CAN_DUPE.

abstract property pixel_format¶

The pixel format that this driver uses for its frame buffer. If a driver doesn’t support setting the pixel format, then this property will always return PixelFormat.RGB1555.

Raises:

TypeError – If trying to set a value that isn’t a PixelFormat.
NotImplementedError – If setting this property on a driver that doesn’t support EnvironmentCall.SET_PIXEL_FORMAT.

Note

Corresponds to RETRO_ENVIRONMENT_SET_PIXEL_FORMAT.

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

abstract property system_av_info¶

The system AV info for the current session. May be None if not yet set.

Initialized from Core.get_system_av_info() some time after this driver is created. After being set, this video driver is immediately reinitialized if necessary.

Raises:: TypeError – If trying to set a value that isn’t a retro_system_av_info.

Note

Corresponds to RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO.

The getter will return a copy of the driver’s retro_system_av_info object to avoid accidental modification of the original.

abstract property geometry¶: The active screen geometry. May be None if system_av_info hasn’t been set yet.

Note

Corresponds to RETRO_ENVIRONMENT_SET_GEOMETRY.

The getter will return a copy of the driver’s retro_game_geometry object to avoid accidental modification of the original.

Caution

When setting this property, this driver’s values of retro_game_geometry.max_width and retro_game_geometry.max_height are not updated.

libretro.h guarantees that RETRO_ENVIRONMENT_SET_GEOMETRY will complete in constant time without needing to reinitialize the driver; this may not be possible if the driver’s framebuffer needs to be reallocated.

abstractmethod get_software_framebuffer(width, height, flags)[source]¶

Return a framebuffer of the given size, usually (but not necessarily) mapped directly into GPU memory. Can be used to accelerate software rendering, as data doesn’t need to be copied between the core and the GPU.

Parameters:

width (int) – The width of the framebuffer, in pixels.
height (int) – The height of the framebuffer, in pixels.
flags (MemoryAccess) – Flags that describe how the core will access the framebuffer.

Return type:

retro_framebuffer | None

Returns:

A retro_framebuffer object with the requested properties, or None if not supported by this VideoDriver.

Raises:

ValueError – If the framebuffer’s width or height is less than 1.
TypeError – If any parameter’s type is not consistent with this method’s signature.

Note

Corresponds to RETRO_ENVIRONMENT_GET_CURRENT_SOFTWARE_FRAMEBUFFER.

abstract property hw_render_interface¶

Returns a retro_hw_render_interface subclass that can be used for rendering operations specific to this VideoDriver.

Will be None if not supported or needed by this driver.

Note

Corresponds to RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE.

abstract property shared_context¶: Whether to create a shared hardware context. Takes effect the next time the driver is reinitialized.

Note

Corresponds to RETRO_ENVIRONMENT_SET_HW_SHARED_CONTEXT.

This property is generally only used by OpenGL and OpenGL ES, but it has its own environment call for historical reasons.

abstractmethod screenshot(prerotate=True)[source]¶

Capture the part of the most recently-rendered frame that would be visible to the player in a typical libretro frontend.

This should account for rotation, geometry dimensions, and aspect ratio.

Parameters:: prerotate (bool) – True if this method should rotate the output buffer’s contents according to rotation, False if it should be left to the frontend.
Return type:: Screenshot | None

class FrameBufferSpecial[source]¶

Bases: Enum

Sentinel return values from VideoDriver.refresh() that aren’t ordinary frame buffers.

DUPE = None¶

HARDWARE = -1¶

classmethod value in self¶

Return True if value is in cls.

value is in cls if: 1) value is a member of cls, or 2) value is the value of one of the cls’s members. 3) value is a pseudo-member (flags)

classmethod self[name]¶: Return the member matching name.

classmethod iter(self)¶: Return members in definition order.

classmethod len(self)¶: Return the number of members (no aliases)

class Screenshot[source]¶

Bases: object

A snapshot of the most recently rendered video frame.

data¶: Buffer containing pixels.

width¶: Width of the screenshot in pixels.

height¶: Height of the screenshot in pixels.

rotation¶: Angle of the screenshot’s rotation.

pixel_format¶: Pixel format of the screenshot.

__init__(data, width, height, rotation, pixel_format)¶

classmethod __new__(*args, **kwargs)¶

exception UnsupportedContextError[source]¶

Bases: RuntimeError

Raised when a core requests a graphics context that a VideoDriver doesn’t support.

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

add_note(note, /)¶: Add a note to the exception

args¶

with_traceback(tb, /)¶: Set self.__traceback__ to tb and return self.