libretro.drivers.video.multi

Types for delegating to different VideoDriver implementations at runtime, depending on the player’s preferences and available hardware resources.

Module Attributes

DEFAULT_DRIVER_MAP

The default mapping from context types to VideoDriver constructors.

Classes

MultiVideoDriver

A video driver that delegates to one of several possible VideoDriver s, depending on what the core or frontend requests.
final class MultiVideoDriver[source]

Bases: VideoDriver

A video driver that delegates to one of several possible VideoDriver s, depending on what the core or frontend requests.

This class is useful for a Core that supports multiple graphics APIs, especially if it can switch between them at runtime.

__init__(drivers=mappingproxy({<HardwareContext.NONE: 0>: <class 'libretro.drivers.video.software.array.ArrayVideoDriver'>, <HardwareContext.OPENGL_CORE: 3>: <class 'libretro.drivers.video.opengl.moderngl.ModernGlVideoDriver'>, <HardwareContext.OPENGL: 1>: <class 'libretro.drivers.video.opengl.moderngl.ModernGlVideoDriver'>}), preferred=HardwareContext.NONE)[source]

Initialize a new multi-video driver with the preferred HardwareContext.

Parameters:
Raises:
refresh(data, width, height, pitch)[source]

Delegate to the active video driver’s VideoDriver.refresh() method.

Return type:

None

property needs_reinit

True if no underlying VideoDriver has been initialized, a new graphics API has been requested with set_context(), or the active driver’s needs_reinit is True.

reinit()[source]

Initialize a new VideoDriver instance based on the most recent graphics API request, or reinitializes the current one if no new context has been requested.

If initializing a new VideoDriver then its pixel_format, system_av_info, rotation, and shared_context are set to the values used by the existing driver (if any) where supported.

Note

Does not use preferred_context.

Return type:

None

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.

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?

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:

Note

Corresponds to RETRO_ENVIRONMENT_GET_PREFERRED_HW_RENDER.

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:
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.

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.

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.

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.

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.

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:

Note

Corresponds to RETRO_ENVIRONMENT_SET_PIXEL_FORMAT.

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.

classmethod __new__(*args, **kwargs)
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.

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.

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.

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.

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

DEFAULT_DRIVER_MAP = mappingproxy({<HardwareContext.NONE: 0>: <class 'libretro.drivers.video.software.array.ArrayVideoDriver'>, <HardwareContext.OPENGL_CORE: 3>: <class 'libretro.drivers.video.opengl.moderngl.ModernGlVideoDriver'>, <HardwareContext.OPENGL: 1>: <class 'libretro.drivers.video.opengl.moderngl.ModernGlVideoDriver'>})

The default mapping from context types to VideoDriver constructors. Defaults may vary based on the platform and installed packages. They are as follows:

HardwareContext.NONE

Always available and mapped to ArrayVideoDriver.

OPENGL_CORE, OPENGL

Mapped to ModernGlVideoDriver if moderngl is installed, absent if not.

VideoDriver s for other graphics APIs have not yet been implemented.