libretro.api.content¶

Types that define the content that can be (or has been) loaded by a Core.

See also

ContentDriver: The Protocol that uses these types to load content in libretro.py.
libretro.drivers.content: libretro.py’s included ContentDriver implementations.

Module Attributes

`ContentPath`	A path to content, supporting filesystem paths and ZIP archive paths.
`ContentData`	Raw content data in memory.
`Content`	Any of the supported ways to provide content to a core.

Functions

`get_extension`(content)	Return the extension of the content file or path, without a leading dot.
`map_content`(content)

Classes

`ContentInfoOverrides`	An indexed and extension-keyed collection of `retro_system_content_info_override`.
`SubsystemContent`	Content for a subsystem, pairing a game type with a sequence of content items.
`Subsystems`	An indexed and identifier-keyed collection of `retro_subsystem_info`.
`retro_game_info`	Describes a game that's been loaded and exposed to a `Core`.
`retro_game_info_ext`	An extended version of `retro_game_info` with additional metadata about the content file, including archive and directory information.
`retro_subsystem_info`	Describes a subsystem that supports loading zero or more content files.
`retro_subsystem_memory_info`	Describes a memory type associated with a subsystem ROM.
`retro_subsystem_rom_info`	Describes a type of ROM (or other data) that can be used with a subsystem.
`retro_system_content_info_override`	Descriptors for core content that needs to be handled differently than described by `Core.get_system_info()`.
`retro_system_info`	Describes the `Core`'s basic properties such as its name, version, and supported file extensions.

class retro_system_info[source]¶

Bases: Structure

Describes the Core’s basic properties such as its name, version, and supported file extensions.

Corresponds to retro_system_info in libretro.h.

See also

Core.get_system_info(): The method used to provide this information to libretro.py.

library_name¶: Human-readable name for the core.

library_version¶: Human-readable version string for the core.

valid_extensions¶: Pipe-delimited string of file extensions the core accepts, without leading dots.

need_fullpath¶: If True, the ContentDriver should not open content files itself, instead letting the Core handle it.

block_extract¶: If True, the ContentDriver should not extract content from compressed archives.

Tip

This is useful for cores that treat the archive itself as content, like most cores for arcade machines.

__deepcopy__(_)[source]¶

Return a deep copy of this system info, including copies of all strings. Intended for use with copy.deepcopy().

>>> import copy
>>> from libretro.api import retro_system_info
>>> info = retro_system_info(library_name=b'TestCore', library_version=b'1.0')
>>> info2 = copy.deepcopy(info)
>>> info == info2
True
>>> info is info2
False
>>> info.library_name == info2.library_name
True
>>> info.library_name is info2.library_name
False

property extensions¶

Yields each extension named in valid_extensions as bytes, or nothing if valid_extensions is None.

>>> from libretro.api import retro_system_info
>>> info = retro_system_info(valid_extensions=b'bin|rom|iso')
>>> list(info.extensions)
[b'bin', b'rom', b'iso']

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

type Content = ContentPath | ContentData | retro_game_info¶: Any of the supported ways to provide content to a core.

type ContentData = bytes | bytearray | memoryview[int] | Buffer¶: Raw content data in memory.

type ContentPath = str | PathLike[str] | PathLike[bytes] | Path¶: A path to content, supporting filesystem paths and ZIP archive paths.

class SubsystemContent[source]¶

Bases: object

Content for a subsystem, pairing a game type with a sequence of content items.

>>> from libretro.api.content import SubsystemContent
>>> sc = SubsystemContent(game_type=0, info=[b'/game.bin'])
>>> sc.game_type
0

game_type¶

info¶

__init__(game_type, info)¶

classmethod __new__(*args, **kwargs)¶

class retro_game_info[source]¶

Bases: Structure

Describes a game that’s been loaded and exposed to a Core.

Corresponds to retro_game_info in libretro.h.

See also

Core.load_game(), Core.load_game_special(): The methods used to load a game into a core.

path¶: Path from which the content was loaded, or None if loaded from memory.

data¶: Pointer to the content data in memory, or None if need_fullpath was set.

size¶

Size of the content data in bytes.

Assigned values are bitwise-masked to fit into a size_t.

meta¶: Optional metadata string. Usually None, but can contain any additional text.

property ext¶

Returns the file extension of path without a leading dot, None if path is None, or an empty string if path has no extension.

>>> from libretro.api import retro_game_info
>>> retro_game_info(path=b'/game.bin').ext
b'bin'
>>> retro_game_info(path=None).ext is None
True
>>> retro_game_info(path=b'/game').ext
b''

__deepcopy__(_)[source]¶

Return a deep copy of this object, including copies of all strings and content data. Intended for use with copy.deepcopy().

>>> import copy
>>> from libretro.api import retro_game_info
>>> info = retro_game_info(path=b'/game.bin')
>>> info2 = copy.deepcopy(info)
>>> info == info2
True
>>> info is info2
False
>>> info.data == info2.data
False

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class retro_subsystem_memory_info[source]¶

Bases: Structure

Describes a memory type associated with a subsystem ROM. Usually refers to save data, but not always.

Corresponds to retro_subsystem_memory_info in libretro.h.

extension¶: File extension used when saving this memory type to disk, e.g. b"srm".

type¶

Memory type identifier. Should be at least 0x100 to avoid conflict with standard memory types.

Assigned values are bitwise-masked to fit into an unsigned int.

See also

RETRO_MEMORY_SAVE_RAM

__deepcopy__(_)[source]¶: Return a deep copy of this object, including copies of strings. Intended for use with copy.deepcopy().

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class retro_subsystem_rom_info[source]¶

Bases: Structure

Describes a type of ROM (or other data) that can be used with a subsystem.

Can be indexed like a Sequence to access this ROM type’s associated memory info.

Corresponds to retro_subsystem_rom_info in libretro.h.

desc¶: Human-readable description of the content type.

valid_extensions¶: Pipe-delimited string of accepted file extensions.

need_fullpath¶: If True, the ContentDriver should populate retro_game_info.path without loading its content into memory.

block_extract¶: If True, the ContentDriver should not extract content from compressed archives.

required¶: If True, the ContentDriver should reject attempts to use the associated subsystem without this ROM.

memory¶: Pointer to an array of memory descriptors associated with this subsystem ROM. May be None if there are no associated memory types (i.e. num_memory is 0).

See also

__getitem__() for a more Pythonic way of accessing this.

num_memory¶

Number of entries in the array pointed to by memory.

Assigned values are bitwise-masked to fit into an unsigned int.

See also

__len__() for a more Pythonic way of accessing this.

len(self)[source]¶

Return num_memory.

>>> from libretro.api import retro_subsystem_rom_info
>>> rom = retro_subsystem_rom_info(num_memory=0)
>>> len(rom)
0

self[index][source]¶

Overloads:

self, index (int) → retro_subsystem_memory_info
self, index (slice[retro_subsystem_memory_info]) → list[retro_subsystem_memory_info]

Return a retro_subsystem_memory_info at the given index, or a list of them if a slice is provided.

Raises:

ValueError – If memory is None.
IndexError – If index is out of the range given by num_memory.

__deepcopy__(memo=None)[source]¶: Return a deep copy of this object, including copies of all strings and subobjects. Intended for use with copy.deepcopy().

property extensions¶

Yields each extension named in valid_extensions, or nothing if valid_extensions is None.

>>> from libretro.api import retro_subsystem_rom_info
>>> rom = retro_subsystem_rom_info(valid_extensions=b'bin|rom')
>>> list(rom.extensions)
[b'bin', b'rom']

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class retro_subsystem_info[source]¶

Bases: Structure

Describes a subsystem that supports loading zero or more content files.

Corresponds to retro_subsystem_info in libretro.h.

desc¶: Human-readable description of the subsystem.

ident¶: Short identifier for the subsystem, used for lookups.

roms¶: Pointer to an array of ROM info structures.

See also

__getitem__() for a more Pythonic way of accessing this.

num_roms¶

Number of entries in the array pointed to by roms.

Assigned values are bitwise-masked to fit into an unsigned int.

See also

__len__() for a more Pythonic way of accessing this.

id¶

Unique identifier for this subsystem.

Assigned values are bitwise-masked to fit into an unsigned int.

len(self)[source]¶: Return num_roms.

self[index][source]¶

Overloads:

self, index (int) → retro_subsystem_rom_info
self, index (slice[retro_subsystem_rom_info]) → list[retro_subsystem_rom_info]

Return a retro_subsystem_rom_info at the given index, or a list of them if a slice is provided.

Raises:

ValueError – If roms is None.
IndexError – If index is out of range.

__deepcopy__(memo=None)[source]¶

Return a deep copy of this subsystem info, including all strings and subobjects. Intended for use with copy.deepcopy().

>>> import copy
>>> from libretro.api import retro_subsystem_info
>>> sub = retro_subsystem_info(desc=b'SGB', ident=b'sgb', id=1)
>>> copy.deepcopy(sub).ident
b'sgb'

property extensions¶: Yields all valid extensions across all ROM slots.

property by_extensions¶

Yields (extension, rom_info) pairs for all ROM slots.

>>> from libretro.api import retro_subsystem_info
>>> sub = retro_subsystem_info(num_roms=0)
>>> list(sub.by_extensions)
[]

by_extension(ext)[source]¶

Return the ROM info for the given file extension.

Parameters:: ext (str | bytes) – The file extension (with or without leading dot).
Raises:: KeyError – If no ROM slot supports the extension.
Return type:: retro_subsystem_rom_info

>>> from libretro.api import retro_subsystem_info
>>> sub = retro_subsystem_info(num_roms=0)
>>> try:
...     sub.by_extension('bin')
... except KeyError:
...     print('Not found')
Not found

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class retro_system_content_info_override[source]¶

Bases: Structure

Descriptors for core content that needs to be handled differently than described by Core.get_system_info().

Corresponds to retro_system_content_info_override in libretro.h.

extensions¶

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

need_fullpath¶

persistent_data¶

__deepcopy__(_)[source]¶

Return a deep copy.

>>> import copy
>>> from libretro.api import retro_system_content_info_override
>>> ov = retro_system_content_info_override(extensions=b'bin')
>>> copy.deepcopy(ov).extensions
b'bin'

get_extensions()[source]¶

Yield each extension in the pipe-delimited extensions field.

Return type:: Iterator[bytes]

>>> from libretro.api import retro_system_content_info_override
>>> ov = retro_system_content_info_override(extensions=b'a|b')
>>> list(ov.get_extensions())
[b'a', b'b']

class retro_game_info_ext[source]¶

Bases: Structure

An extended version of retro_game_info with additional metadata about the content file, including archive and directory information.

Corresponds to retro_game_info_ext in libretro.h.

>>> from libretro.api import retro_game_info_ext
>>> info = retro_game_info_ext(full_path=b'/games/test.bin', ext=b'bin')
>>> info.ext
b'bin'

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

full_path¶: Full path to the content file. Can be None if file_in_archive is True.

archive_path¶: Path to the archive containing the content file, if applicable. Can be None if file_in_archive is False.

archive_file¶: Path to the content file within the archive, if applicable. Can be None if file_in_archive is False.

dir¶: Path of the directory containing the content file if file_in_archive is False, or to the directory containing the archive itself if True.

name¶

A ‘canonical’ name for the content file without an extension, intended for loading complementary files.

If file_in_archive is False, this is the basename of full_path without ext. Otherwise, it can be the basename of archive_path or archive_file (also without ext).

ext¶: Contains the file extension of the content file. If file_in_archive is False, this is the extension of full_path. Otherwise, it can be the extension of archive_path.

meta¶: Optional metadata string, similar to retro_game_info.meta.

data¶

Pointer to the content data in memory.

Can be None if need_fullpath or an overriding retro_system_content_info_override.need_fullpath is True.

size¶

Size of the content data in bytes.

Assigned values are bitwise-masked to fit into a size_t.

file_in_archive¶: True if the content is inside an archive file.

persistent_data¶: If True, the ContentDriver must keep data in memory until Core.deinit() completes. Otherwise, the ContentDriver may unload it after Core.load_game() completes.

__deepcopy__(_)[source]¶

Return a deep copy of this object, including copies of all strings and content data. Intended for use with copy.deepcopy().

>>> import copy
>>> from libretro.api import retro_game_info_ext
>>> info = retro_game_info_ext(full_path=b'/test.bin')
>>> copy.deepcopy(info).full_path
b'/test.bin'

map_content(content)[source]¶

Overloads:

content (None) → Iterator[None]
content (Content) → Iterator[retro_game_info]

Context manager for mapping a content file into memory. The content is mapped on entering, and unmapped on exiting.

get_extension(content)[source]¶

Return the extension of the content file or path, without a leading dot.

Return type:: bytes | None

class Subsystems[source]¶

Bases: Sequence[retro_subsystem_info]

An indexed and identifier-keyed collection of retro_subsystem_info.

Supports lookup by integer index, string identifier, or bytes identifier.

>>> from libretro.api.content import Subsystems
>>> from libretro.api import retro_subsystem_info
>>> subs = Subsystems([retro_subsystem_info(desc=b'SGB', ident=b'sgb', id=1)])
>>> len(subs)
1
>>> subs[b'sgb'].id
1

__init__(subsystems)[source]¶

Initialize from a sequence of retro_subsystem_info.

Parameters:: subsystems (Sequence[retro_subsystem_info]) – The subsystem info entries.
Raises:: TypeError – If subsystems is not a sequence or contains non-retro_subsystem_info elements.

>>> from libretro.api.content import Subsystems
>>> subs = Subsystems([])
>>> len(subs)
0

self[item][source]¶

Overloads:

self, item (int | str | bytes) → retro_subsystem_info
self, item (slice) → Sequence[retro_subsystem_info]

Return a subsystem info by index or identifier.

Parameters:

item (int | str | bytes | slice) – An integer index, string/bytes identifier, or slice.

Raises:

IndexError – If an integer index is out of range.
KeyError – If a string/bytes identifier is not found.

>>> from libretro.api.content import Subsystems
>>> from libretro.api import retro_subsystem_info
>>> subs = Subsystems([retro_subsystem_info(ident=b'sgb', id=1)])
>>> subs[0].id
1

item in self[source]¶

Test for membership by identifier or value.

>>> from libretro.api.content import Subsystems
>>> from libretro.api import retro_subsystem_info
>>> subs = Subsystems([retro_subsystem_info(ident=b'sgb')])
>>> b'sgb' in subs
True

iter(self)[source]¶

Iterate over the subsystem info entries.

Return type:: Iterator[retro_subsystem_info]

>>> from libretro.api.content import Subsystems
>>> list(Subsystems([]))
[]

len(self)[source]¶

Return the number of subsystem info entries.

Return type:: int

>>> from libretro.api.content import Subsystems
>>> len(Subsystems([]))
0

classmethod __new__(*args, **kwargs)¶

count(value) → integer -- return number of occurrences of value¶

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

class ContentInfoOverrides[source]¶

Bases: Sequence[retro_system_content_info_override]

An indexed and extension-keyed collection of retro_system_content_info_override.

Supports lookup by integer index or by file extension.

>>> from libretro.api.content import ContentInfoOverrides
>>> from libretro.api import retro_system_content_info_override
>>> overrides = ContentInfoOverrides([retro_system_content_info_override(extensions=b'bin')])
>>> len(overrides)
1

classmethod __new__(*args, **kwargs)¶

count(value) → integer -- return number of occurrences of value¶

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

__init__(overrides)[source]¶

Initialize from a sequence of retro_system_content_info_override.

Parameters:: overrides (Sequence[retro_system_content_info_override]) – The override entries.

>>> from libretro.api.content import ContentInfoOverrides
>>> len(ContentInfoOverrides([]))
0

self[item][source]¶

Overloads:

self, item (int | str | bytes) → retro_system_content_info_override
self, item (slice) → Sequence[retro_system_content_info_override]

Return an override by index, extension, or slice.

Parameters:

item (int | slice | str | bytes) – An integer index, extension string/bytes, or slice.

Raises:

IndexError – If an integer index is out of range.
KeyError – If an extension is not found.

>>> from libretro.api.content import ContentInfoOverrides
>>> from libretro.api import retro_system_content_info_override
>>> overrides = ContentInfoOverrides([retro_system_content_info_override(extensions=b'bin')])
>>> overrides[0].extensions
b'bin'
>>> overrides[b'bin'].extensions
b'bin'

item in self[source]¶

Test if the given item is in the overrides list.

Parameters:: item (str | bytes | retro_system_content_info_override | object) – If a retro_system_content_info_override, checks for an exact match. If str or bytes, checks for a matching extension.
Return type:: bool

>>> from libretro.api.content import ContentInfoOverrides
>>> from libretro.api import retro_system_content_info_override
>>> overrides = ContentInfoOverrides([retro_system_content_info_override(extensions=b'bin')])
>>> b'bin' in overrides
True
>>> b'rom' in overrides
False

iter(self)[source]¶

Iterate over the override entries.

Return type:: Iterator[retro_system_content_info_override]

>>> from libretro.api.content import ContentInfoOverrides
>>> list(ContentInfoOverrides([]))
[]

len(self)[source]¶

Return the number of override entries.

Return type:: int

>>> from libretro.api.content import ContentInfoOverrides
>>> len(ContentInfoOverrides([]))
0

property by_extension¶

A read-only mapping from extension to override.

>>> from libretro.api.content import ContentInfoOverrides
>>> from libretro.api import retro_system_content_info_override
>>> overrides = ContentInfoOverrides([retro_system_content_info_override(extensions=b'bin')])
>>> b'bin' in overrides.by_extension
True