libretro.api

Python equivalents of the C data structures defined in libretro.h.

Almost all types in this module are ctypes-based wrappers around their equivalents in libretro.h.

Although these types are primarily meant to be used with the drivers in libretro.drivers, they do not depend on any driver protocols or implementations.

They follow these conventions unless otherwise stated:

Naming

• All function pointer types and Structure subclasses are named exactly the same as their C counterparts.

• All explicit enum types are given CamelCase names that match the name of their C counterparts with the common RETRO_ prefix removed.

• All groups of related #define constants are given CamelCase type names derived from their common prefix in C.

• All enum values (both explicit and #defines ) are named in ALL_CAPS_SNAKE_CASE, with their common prefix removed.

Type Conversions

This module’s types rely heavily on the conversions defined by ctypes. The linked documentation provides details, but in a nutshell:

• Python objects are implicitly converted to equivalent C data types when:

  • Assigned to a Structure field, or;

  • Stored as an element in an appropriately-typed Array, or;

  • Assigned as the target of a _Pointer (or equivalent TypedPointer), or;

  • Passed as an argument to a C function defined with CFUNCTYPE() (or the equivalent TypedFunctionPointer).

• C data types are implicitly converted to equivalent ctypes objects or Python primitives when:

  • Accessed as a field of a Structure, or;

  • Accessed as an element of an Array, or;

  • Accessed as the target of a _Pointer (or equivalent TypedPointer), or;

  • Returned as the result of a C function defined with CFUNCTYPE() (or the equivalent TypedFunctionPointer).

• Python classes that implement AsParameter can be implicitly converted to C data types when passed to CFUNCTYPE()-defined functions.

• C integers are converted to Python ints regardless of their size or signedness.

• Python ints are masked to fit the size and signedness of the target C integer type when converted to C.

• C floating-point types are converted to and from Python floats.

• Python bytes objects are converted to and from NULL-terminated char*s.

• NULL C pointers of any type are converted to and from None.

• C bools are converted to and from Python bools.

• C void* pointers are converted to and from ints.

• Subclasses of any ctypes primitive are not implicitly converted to Python primitives.

See also

libretro.ctypes

Various ctypes-compatible types and utility functions.

Additional Methods

copy.deepcopy()

Unless otherwise noted, all structs can be copied with copy.deepcopy(); the struct itself and its fields (including strings and buffers) are all deep-copied. For example:

import copy
from libretro.api import retro_controller_description

desc = retro_controller_description(b'Game Pad', 5)
desc_copy = copy.deepcopy(desc)

assert desc == desc_copy

desc.desc = b'Another Game Pad'
assert desc != desc_copy

Collection Protocols

Where applicable, structs that logically represent arrays of items (e.g. retro_controller_info) implement collections.abc.Sequence to allow indexing and iteration over the items, plus __setitem__ to update values. For example:

from libretro.api import retro_controller_info

info = retro_controller_info()
info.num_descriptions = 2
info.descriptions[0] = retro_controller_description(b'Game Pad', 5)
info.descriptions[1] = retro_controller_description(b'Analog Stick', 2)

assert len(info) == 2
assert info[0].desc == b'Game Pad'
assert info[1].desc == b'Analog Stick'

See also

libretro.drivers for driver protocols that use these types.

Modules

audio	Audio callback and sample rendering types.
av	Types to describe the parameters of a core's rendered audio and video.
camera	Interface and types for providing video input to a Core.
content	Types that define the content that can be (or has been) loaded by a Core.
disk	Types and callbacks for using the emulated system's disk drives, if any.
environment	Types for interfacing between a Core and libretro.py's driver implementations.
input	Input device definitions, state representations, and callbacks.
led	Types for allowing Cores to control LED indicators on the host device.
location	Geographic location service interface types.
log	Types for allowing Cores to log messages.
memory	Types that describe the address space of the Core's emulated memory.
message	Types that allow Cores to display notifications on the frontend's OSD.
microphone	Microphone audio capture interface types.
midi	MIDI input/output interface types.
netpacket	Network packet exchange interface types for multiplayer.
options	Core option definitions, values, categories, and internationalization.
perf	Performance counter and SIMD feature detection types.
power	Types for exposing a frontend's power status to a Core.
proc	Types for retrieving core functions beyond the standard retro_* API functions exposed by Core.
rumble	Rumble (force feedback) interface types.
savestate	Types that define serialization quirks and savestate contexts.
sensor	Types for providing sensor input to cores.
timing	Types for managing the rate at which the Core runs.
user	User interface language types and constants.
vfs	Virtual filesystem (VFS) interface types and callbacks.
video	Video callback and rendering types.