libretro.drivers.video.opengl.moderngl

VideoDriver implementation backed by moderngl and PyOpenGL.

See also

VideoDriver

The protocol this driver implements.

Classes

ModernGlVideoDriver

A video driver that exposes an OpenGL context to the core via moderngl and PyOpenGL.

final class ModernGlVideoDriver

Bases: VideoDriver

A video driver that exposes an OpenGL context to the core via moderngl and PyOpenGL.

__init__(vertex_shader=None, fragment_shader=None, varyings=('transformedTexCoord',), window=None)

Initialize the video driver. Does not create an OpenGL context; that will occur when reinit() is called.

This driver uses a basic shader program, but custom shaders can be provided.

Warning:

The shaders are not compiled or linked until the OpenGL context is created, so GLSL errors won’t be detected until then.

Parameters:

• vertex_shader (str | None) – The GLSL source of the vertex shader to use for rendering, or None to use the built-in default.

• fragment_shader (str | None) – The GLSL source of the fragment shader to use for rendering, or None to use the built-in default.

• varyings (Sequence[str]) – The names of the “varyings” (vertex value outputs) to use.

__del__()

Clean up allocated OpenGL resources and the underlying context.

set_context(callback)

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.

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)

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.

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.

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.

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:

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

2. Release all libretro.py-managed graphics resources.

3. Release the graphics context if switching to a different graphics API or making changes that require a new context.

4. Initialize a new graphics context if necessary.

5. Initialize internal resources for libretro.py.

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

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

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

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.

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

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

classmethod __new__(*args, **kwargs)

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.

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.

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.

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.