libretro.session¶

High-level harness that drives a Core through its libretro lifecycle.

See also

libretro.builder: The SessionBuilder factory used to construct a configured Session.

Classes

Session

A configured libretro core paired with the drivers that satisfy its environment calls.

class Session[source]¶

Bases: CompositeEnvironmentDriver, Generic

A configured libretro core paired with the drivers that satisfy its environment calls.

Use Session as a context manager: entering it loads the core (and game, if any) and wires up callbacks; exiting it unloads the game and deinitializes the core. Each constructor argument selects which driver implementation to use for one libretro subsystem; most are optional and default to None, in which case the matching env-call returns failure.

See also

SessionBuilder: Fluent builder that constructs a Session with sensible defaults.

__init__(core, game, audio, input, video, content=None, overscan=None, message=None, options=None, path=None, rumble=None, sensor=None, camera=None, log=None, perf=None, location=None, user=None, vfs=None, led=None, av_enable=None, midi=None, timing=None, preferred_hw=None, driver_switch_enable=None, savestate_context=None, jit_capable=None, mic=None, device_power=None)[source]¶

Initialize the session with a core, optional game content, and driver implementations.

Parameters:

core (Core | CDLL | str | PathLike[str] | PathLike[bytes]) – The libretro core to load. Accepts a Core, an already-loaded ctypes.CDLL, or a path to a shared library on disk.
game (TypeAliasType | SubsystemContent | None) – The content to pass to retro_load_game (or retro_load_game_special), or None to load the core without content.
audio (TypeVar(_Audio, bound= AudioDriver)) – Required audio driver.
input (TypeVar(_Input, bound= InputDriver)) – Required input driver.
video (TypeVar(_Video, bound= VideoDriver)) – Required video driver.
content (TypeVar(_Content, bound= ContentDriver | None)) – Optional content driver that resolves Content references to loaded files.
overscan (bool | None) – Initial value for the overscan env-call response, or None to leave it unset.
message (TypeVar(_Message, bound= MessageDriver | None)) – Optional driver that handles RETRO_ENVIRONMENT_SET_MESSAGE.
options (TypeVar(_Option, bound= OptionDriver | None)) – Optional core-options driver.
path (TypeVar(_Path, bound= PathDriver | None)) – Optional driver that supplies system/save/asset directory paths.
rumble (TypeVar(_Rumble, bound= RumbleDriver | None)) – Optional rumble driver.
sensor (TypeVar(_Sensor, bound= SensorDriver | None)) – Optional motion-sensor driver.
camera (TypeVar(_Camera, bound= CameraDriver | None)) – Optional camera driver.
log (TypeVar(_Log, bound= LogDriver | None)) – Optional log driver.
perf (TypeVar(_Perf, bound= PerfDriver | None)) – Optional performance-counter driver.
location (TypeVar(_Location, bound= LocationDriver | None)) – Optional geolocation driver.
user (TypeVar(_User, bound= UserDriver | None)) – Optional driver that exposes username and language to the core.
vfs (TypeVar(_Vfs, bound= FileSystemDriver | None)) – Optional virtual filesystem driver.
led (TypeVar(_Led, bound= LedDriver | None)) – Optional LED driver.
av_enable (AvEnableFlags | None) – Initial value for the audio_video_enable env-call response, or None to leave it unset.
midi (TypeVar(_Midi, bound= MidiDriver | None)) – Optional MIDI driver.
timing (TypeVar(_Timing, bound= TimingDriver | None)) – Optional timing driver.
preferred_hw (HardwareContext | None) – Initial value for the preferred_hw_render env-call response, or None to leave it unset.
driver_switch_enable (bool | None) – Whether RETRO_ENVIRONMENT_GET_AUDIO_VIDEO_ENABLE should report driver-switch support, or None to leave it unset.
savestate_context (SavestateContext | None) – Initial value for the savestate_context env-call response, or None to leave it unset.
jit_capable (bool | None) – Initial value for the jit_capable env-call response, or None to leave it unset.
mic (TypeVar(_Mic, bound= MicrophoneDriver | None)) – Optional microphone driver.
device_power (TypeVar(_Power, bound= PowerDriver | None)) – Optional driver that reports device battery state.

Raises:

TypeError – If core is not a Core, ctypes.CDLL, or a filesystem path.

__enter__()[source]¶

Initialize the core, register callbacks, and load content.

Returns:: This session, suitable for use inside a with block.
Raises:: RuntimeError – If the core’s API version is incompatible, its system info is incomplete, or content loading fails.

__exit__(exc_type, exc_val, exc_tb)[source]¶

Unload the game and deinitialize the core, propagating exceptions unless the core shut down.

Returns:: True if a CoreShutDownException should be suppressed.

property core¶

The active CoreInterface for this session.

Raises:: CoreShutDownException – If the session has exited or the core has shut down.

property is_exited¶: Whether this session has exited its with block.

property system_directory¶

The system directory the path driver advertises to the core.

None if no path driver was configured.

property system_dir¶: Alias for system_directory.

property save_directory¶

The save directory the path driver advertises to the core.

None if no path driver was configured.

property save_dir¶: Alias for save_directory.

property max_users¶: The maximum number of input ports the input driver advertises.

property content_info_overrides¶

Content-info overrides registered by the core, exposed by the content driver.

None if no content driver was configured.

run()[source]¶

Advance the core by one frame.

Polls per-frame drivers, ticks the timing driver, and calls retro_run.

Raises:: CoreShutDownException – If the session has exited or the core has shut down.
Return type:: None

reset()[source]¶

Reset the running core, equivalent to flipping the emulated power switch.

Raises:: CoreShutDownException – If the session has exited or the core has shut down.
Return type:: None

set_controller_port_device(port, device)[source]¶

Bind a controller class to an input port.

Parameters:

port (Port (int)) – The input port to update.
device (int) – The RETRO_DEVICE_* controller class to assign to port.

Raises:

CoreShutDownException – If the session has exited or the core has shut down.

Return type:

None

cheat_reset()[source]¶

Clear all cheats currently registered with the core.

Raises:: CoreShutDownException – If the session has exited or the core has shut down.
Return type:: None

cheat_set(index, enabled, code)[source]¶

Parameters:

index (int) – The cheat slot to set.
enabled (bool) – Whether the cheat is active.
code (bytes | bytearray | str) – The cheat code in the core’s expected format.

Raises:

CoreShutDownException – If the session has exited or the core has shut down.

Return type:

None

key in self¶

self[_DictEnvironmentDriver__key]¶

Return type:: Callable[[c_void_p], bool]

iter(self)¶

Return type:: Iterator[EnvironmentCall]

len(self)¶

classmethod __new__(*args, **kwargs)¶

property audio¶: Return the AudioDriver supplied at construction time.

audio_sample(left, right)¶

Receive a single stereo audio sample from the core.

Parameters:

left (int) – The left-channel sample as a signed 16-bit integer.
right (int) – The right-channel sample as a signed 16-bit integer.

See also

retro_audio_sample_t: The C function pointer type whose signature this method implements.

Return type:: None

audio_sample_batch(data, frames)¶

Receive a batch of interleaved stereo audio frames from the core.

Parameters:

data (LP_c_short) – Pointer to interleaved signed 16-bit stereo samples.
frames (int) – Number of stereo frames available in data.

Return type:

int

Returns:

The number of frames consumed.

See also

retro_audio_sample_batch_t: The C function pointer type whose signature this method implements.

property av_enable¶

Return the AvEnableFlags the frontend exposes to the core, or None if unset.

See also

EnvironmentCall.GET_AUDIO_VIDEO_ENABLE: The environment call that queries this value.

property camera¶: Return the CameraDriver supplied at construction time, or None if absent.

property can_dupe¶

Return whether the underlying VideoDriver supports frame duping.

See also

EnvironmentCall.GET_CAN_DUPE: The environment call that queries this value.

property content¶: Return the ContentDriver supplied at construction time, or None if absent.

property controller_info¶

Return the controller descriptions the core registered, or None if none were set.

See also

EnvironmentCall.SET_CONTROLLER_INFO: The environment call that registers this information.

property core_options_version¶

Return the core-options API version supported by the option driver, or None if absent.

See also

EnvironmentCall.GET_CORE_OPTIONS_VERSION: The environment call that queries this value.

environment(cmd, data)¶

Dispatch an environment call from the core.

Implementations route cmd to the appropriate _<env_call_name> helper (e.g. _get_variable for RETRO_ENVIRONMENT_GET_VARIABLE) and return True if the call was handled successfully.

Parameters:

cmd (int) – The RETRO_ENVIRONMENT_* command identifier.
data (c_void_p) – Pointer to the command-specific data buffer, interpreted according to cmd.

Return type:

bool

Returns:

True if the call was handled, False if the command is unsupported or failed.

See also

retro_environment_t: The C function pointer type whose signature this method implements.

property geometry¶

Return the current frame geometry from the underlying VideoDriver.

See also

EnvironmentCall.SET_GEOMETRY: The environment call that updates this value.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

get_proc_address(sym, funtype=None)¶

Overloads:

self, sym (str | bytes), funtype (type[T]) → T | None
self, sym (str | bytes), funtype (None) → retro_proc_address_t | None
self, sym (Literal[b’’, ‘’]), funtype (type[_CFunctionType] | None) → None
self, sym (str | bytes), funtype (type[TypedFunctionPointer[R, P]]) → TypedFunctionPointer[R, P] | None

Look up a function pointer the core exposed via its proc-address interface.

Parameters:

sym – The name of the symbol to look up; an empty name returns None.
funtype – An optional ctypes function type to cast the returned pointer to; if omitted, a generic retro_proc_address_t is returned.

Returns:

The requested function pointer cast to funtype, or None if the core has not registered a proc-address interface, the symbol is empty, or the lookup failed.

property hw_shared_context¶

Return whether the underlying VideoDriver is configured for a shared HW context.

See also

EnvironmentCall.SET_HW_SHARED_CONTEXT: The environment call that enables shared-context mode.

property input¶: Return the InputDriver supplied at construction time.

property input_bitmasks¶

Return whether the underlying InputDriver supports input bitmasks.

See also

EnvironmentCall.GET_INPUT_BITMASKS: The environment call that queries this value.

property input_descriptors¶

Return the input descriptors registered by the core, or None if none were set.

See also

EnvironmentCall.SET_INPUT_DESCRIPTORS: The environment call that registers these descriptors.

input_poll()¶

Poll input devices for new input state.

Called by the core once per frame before any input_state() queries.

See also

retro_input_poll_t: The C function pointer type whose signature this method implements.

Return type:: None

input_state(port, device, index, id)¶

Return the current input state for a given device control.

Parameters:

port (Port (int)) – The input port being queried.
device (int) – The RETRO_DEVICE_* device class.
index (int) – The sub-device index (e.g. analog stick number).
id (int) – The button or axis identifier within the device class.

Return type:

int

Returns:

The control’s current state, encoded per libretro’s input conventions.

See also

retro_input_state_t: The C function pointer type whose signature this method implements.

property is_shutdown¶

Return True if the core has requested a shutdown via the environment call.

See also

EnvironmentCall.SHUTDOWN: The environment call that flips this flag.

items() → a set-like object providing a view on D's items¶

property jit_capable¶

Return whether the frontend permits JIT compilation, or None if unset.

See also

EnvironmentCall.GET_JIT_CAPABLE: The environment call that queries this value.

property keyboard_callback¶

Return the keyboard callback registered by the core, or None if none was set.

See also

EnvironmentCall.SET_KEYBOARD_CALLBACK: The environment call that registers this callback.

keys() → a set-like object providing a view on D's keys¶

property led¶: Return the LedDriver supplied at construction time, or None if absent.

property location¶: Return the LocationDriver supplied at construction time, or None if absent.

property log¶: Return the LogDriver supplied at construction time, or None if absent.

property memory_maps¶

Return the memory map the core registered, or None if none was set.

See also

EnvironmentCall.SET_MEMORY_MAPS: The environment call that registers this information.

property message¶: Return the MessageDriver supplied at construction time, or None if absent.

property mic¶: Return the MicrophoneDriver supplied at construction time, or None if absent.

property midi¶: Return the MidiDriver supplied at construction time, or None if absent.

property options¶: Return the OptionDriver supplied at construction time, or None if absent.

property overscan¶

Return whether the frontend wants overscan to be visible, or None if unset.

See also

EnvironmentCall.GET_OVERSCAN: The environment call that queries this value.

property path¶: Return the PathDriver supplied at construction time, or None if absent.

property perf¶: Return the PerfDriver supplied at construction time, or None if absent.

property performance_level¶

Return the performance level the core has reported, or None if unset.

See also

EnvironmentCall.SET_PERFORMANCE_LEVEL: The environment call that sets this value.

property pixel_format¶

Return the PixelFormat currently set on the underlying VideoDriver.

See also

EnvironmentCall.SET_PIXEL_FORMAT: The environment call that updates this value.

property power¶: Return the PowerDriver supplied at construction time, or None if absent.

property preferred_hw_render¶

Return the preferred HardwareContext exposed to the core, or None if unset.

See also

EnvironmentCall.GET_PREFERRED_HW_RENDER: The environment call that queries this value.

property proc_address_callback¶

Return the retro_get_proc_address_interface registered by the core, if any.

See also

EnvironmentCall.SET_PROC_ADDRESS_CALLBACK: The environment call that registers this interface.

static return_on_raise(default)¶

Ctypes doesn’t propagate exceptions out of callbacks, so this is necessary to detect an error in a driver instead of just swallowing it with a warning.

Return type:: Callable[[Callable[[ParamSpec(P)], TypeVar(T)]], Callable[[ParamSpec(P)], TypeVar(T)]]

property rotation¶

Return the screen Rotation currently set on the underlying VideoDriver.

See also

EnvironmentCall.SET_ROTATION: The environment call that updates this value.

property rumble¶: Return the RumbleDriver supplied at construction time, or None if absent.

property savestate_context¶

Return the SavestateContext the frontend exposes to the core, or None if unset.

See also

EnvironmentCall.GET_SAVESTATE_CONTEXT: The environment call that queries this value.

property sensor¶: Return the SensorDriver supplied at construction time, or None if absent.

property serialization_quirks¶

Return the SerializationQuirks the core declared, or None if unset.

See also

EnvironmentCall.SET_SERIALIZATION_QUIRKS: The environment call that sets these flags.

property subsystems¶

Return the subsystem info the core registered, or None if no content driver is set.

See also

EnvironmentCall.SET_SUBSYSTEM_INFO: The environment call that registers this information.

property support_achievements¶

Return whether the core supports achievements, or None if it has not declared.

See also

EnvironmentCall.SET_SUPPORT_ACHIEVEMENTS: The environment call that sets this value.

property support_no_game¶

Return whether the core can run without content, or None if no content driver is set.

See also

EnvironmentCall.SET_SUPPORT_NO_GAME: The environment call that sets this value.

property timing¶: Return the TimingDriver supplied at construction time, or None if absent.

property user¶: Return the UserDriver supplied at construction time, or None if absent.

values() → an object providing a view on D's values¶

property vfs¶: Return the FileSystemDriver supplied at construction time, or None if absent.

property video¶: Return the VideoDriver supplied at construction time.

video_refresh(data, width, height, pitch)¶

Receive one frame of video output from the core.

Parameters:

data (c_void_ptr) – Pointer to the frame buffer in the core’s current pixel format, or None if the core asked the frontend to duplicate the previous frame.
width (int) – Width of the frame in pixels.
height (int) – Height of the frame in pixels.
pitch (int) – Number of bytes per scanline in data.

See also

retro_video_refresh_t: The C function pointer type whose signature this method implements.

Return type:: None