libretro.drivers.video.software.base¶

Abstract base class for software-rendered VideoDriver implementations.

See also

VideoDriver: The protocol the base class implements.

Classes

SoftwareVideoDriver

A base class for software-only video drivers.

class SoftwareVideoDriver[source]¶

Bases: VideoDriver, ABC

A base class for software-only video drivers.

Provides common overrides that would be the same for all software-only drivers.

property supported_contexts¶

Returns:: A set containing only HardwareContext.NONE.

property active_context¶

Always returns HardwareContext.NONE, as software-rendered drivers lack a hardware context.

Returns:: HardwareContext.NONE.

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.

final set_context(callback)[source]¶

No-op if the context type is HardwareContext.NONE; raises a RuntimeError otherwise.

Return type:: None

property current_framebuffer¶

Returns:: None, as software-rendered drivers don’t have a hardware framebuffer.

final get_proc_address(sym)[source]¶

Return type:: None
Returns:: None, as software-rendered drivers don’t have any hardware functions to call.

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

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

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)¶

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

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.

abstractmethod refresh(data, width, height, pitch)¶

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.

abstractmethod reinit()¶

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

abstractmethod screenshot(prerotate=True)¶

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

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.