Data Structures
struct	SDL_LibretroCategory
	A group of related core options. More...

struct	SDL_LibretroOption
	A core option and its current state. More...

struct	SDL_LibretroOptionValue
	One selectable value for a core option. More...

Macros
#define	SDL_LIBRETRO_MAJOR_VERSION 0
	The major version of SDL_Libretro.

#define	SDL_LIBRETRO_MICRO_VERSION 0
	The micro/patch version of SDL_Libretro.

#define	SDL_LIBRETRO_MINOR_VERSION 1
	The minor version of SDL_Libretro.

#define	SDL_LIBRETRO_VERSION SDL_VERSIONNUM(SDL_LIBRETRO_MAJOR_VERSION, SDL_LIBRETRO_MINOR_VERSION, SDL_LIBRETRO_MICRO_VERSION)
	Retrieves an integer representation of the of the SDL_Libretro version.

#define	SDL_LIBRETRO_VERSION_ATLEAST(X, Y, Z) (SDL_LIBRETRO_VERSION >= SDL_VERSIONNUM(X, Y, Z))
	Checks if SDL_Libretro is at least the given version.

Typedefs
typedef struct SDL_LibretroCategory	SDL_LibretroCategory
	A group of related core options.

typedef enum SDL_LibretroFitMode	SDL_LibretroFitMode
	When rendering the libretro context, determine how to display within the destination.

typedef struct SDL_LibretroOption	SDL_LibretroOption
	A core option and its current state.

typedef struct SDL_LibretroOptionValue	SDL_LibretroOptionValue
	One selectable value for a core option.

Enumerations
enum	SDL_LibretroFitMode { }
	When rendering the libretro context, determine how to display within the destination. More...

Functions
bool	SDL_Libretro_AreOptionsDirty (SDL_Libretro *lr)
	Retrieves whether the options have been changed since the last time they were checked.

SDL_Libretro *	SDL_Libretro_Create (void)
	Builds a libretro context.

SDL_Surface *	SDL_Libretro_CreateSurface (const SDL_Libretro *lr)
	Creates a new surface from the current libretro context.

bool	SDL_Libretro_CycleOptionValue (SDL_Libretro lr, const char key, int direction)
	Advance a core option to the next (+1) or previous (-1) value.

void	SDL_Libretro_Destroy (SDL_Libretro *lr)
	Destroys the given libretro context.

float	SDL_Libretro_GetAspectRatio (const SDL_Libretro *lr)
	Gets the aspect ratio for the libretro context.

const SDL_LibretroCategory *	SDL_Libretro_GetCategory (const SDL_Libretro lr, const char key)
	Retrieve an option category by key, or NULL if there's no such category.

const SDL_LibretroCategory *	SDL_Libretro_GetCategoryByIndex (const SDL_Libretro *lr, unsigned index)
	Retrieve an option category by index, or NULL if out of range.

unsigned	SDL_Libretro_GetCategoryCount (const SDL_Libretro *lr)
	Get the number of option categories registered by the core.

const char *	SDL_Libretro_GetContentExtension (const SDL_Libretro *lr)
	Get the extension of the loaded content, as it appears in the path.

const char *	SDL_Libretro_GetCoreName (const SDL_Libretro *lr)
	Retrieve the name of the libretro core that's actively loaded.

const char *	SDL_Libretro_GetCoreVersion (const SDL_Libretro *lr)
	Retrieves the version of the libretro core that's actively loaded.

size_t	SDL_Libretro_GetFileName (char dst, size_t dstSize, const char path, bool withExtension)
	Copy the file name portion of a path into a caller-provided buffer.

bool	SDL_Libretro_GetInputDescriptor (const SDL_Libretro lr, unsigned index, unsigned port, unsigned device, unsigned id, const char **description)
	Retrieve an input descriptor by index.

unsigned	SDL_Libretro_GetInputDescriptorCount (const SDL_Libretro *lr)
	Retrieve the number of input descriptors provided by a Libretro core.

SDL_LogPriority	SDL_Libretro_GetLogLevel (const SDL_Libretro *lr)
	Retrieve the threshold for logs that will be posted.

void *	SDL_Libretro_GetMapAddress (const SDL_Libretro lr, size_t address, size_t regionRemaining)
	Translate an emulated (guest) address to a live host pointer via the memory map.

void *	SDL_Libretro_GetMemoryData (const SDL_Libretro lr, unsigned memoryType, size_t size)
	Get a pointer to a core memory region and its size.

unsigned	SDL_Libretro_GetMemoryMapCount (const SDL_Libretro *lr)
	Get the number of memory-map descriptors the core has published.

bool	SDL_Libretro_GetMemoryMapDescriptor (const SDL_Libretro lr, unsigned index, Uint64 flags, void *ptr, size_t offset, size_t start, size_t select, size_t disconnect, size_t len, const char **addrspace)
	Retrieve one memory-map descriptor by index.

const char *	SDL_Libretro_GetMessage (SDL_Libretro *lr)
	Gets the most relevent libretro message to display from the queue.

const SDL_LibretroOption *	SDL_Libretro_GetOption (const SDL_Libretro lr, const char key)
	Retrieve details about a given core option.

const SDL_LibretroOption *	SDL_Libretro_GetOptionByIndex (const SDL_Libretro *lr, unsigned index)
	Retrieve a core option by its registration index, or NULL if out of range.

unsigned	SDL_Libretro_GetOptionCount (const SDL_Libretro *lr)
	Get the number of core options that have been set.

const char *	SDL_Libretro_GetOptionValue (SDL_Libretro lr, const char key)
	Get a core option's current value, or NULL if there's no such option.

const char *	SDL_Libretro_GetOptionValueLabel (SDL_Libretro lr, const char key)
	Get the human-readable label for a core option's current value.

unsigned	SDL_Libretro_GetPerformanceLevel (const SDL_Libretro *lr)
	Get the performance level the core requested via SET_PERFORMANCE_LEVEL.

unsigned	SDL_Libretro_GetPortDevice (const SDL_Libretro *lr, unsigned port)
	Get the device type assigned to a controller port.

SDL_Renderer *	SDL_Libretro_GetRenderer (const SDL_Libretro *lr)
	Get the renderer the context draws into.

bool	SDL_Libretro_GetRewindEnabled (const SDL_Libretro *lr)
	Check whether the rewind system is enabled (independent of current direction).

size_t	SDL_Libretro_GetRewindMemoryLimit (const SDL_Libretro *lr)
	Get the current rewind memory budget in bytes (0 if unbounded).

size_t	SDL_Libretro_GetRewindMemoryUsage (const SDL_Libretro *lr)
	Get the approximate memory currently held by the rewind buffer, in bytes.

double	SDL_Libretro_GetRewindRemaining (const SDL_Libretro *lr)
	Calculates the amount of rewind time remaining in the buffer.

size_t	SDL_Libretro_GetSavePath (const SDL_Libretro lr, const char extension, char *dst, size_t dstSize)
	Build a path in the save directory for the currently loaded content.

void	SDL_Libretro_GetSize (const SDL_Libretro lr, int w, int *h)
	Gets the width and heigh tof the given libretro context.

size_t	SDL_Libretro_GetStateSize (const SDL_Libretro *lr)
	Retrieves the size of serialized states.

const char *	SDL_Libretro_GetValidExtensions (const SDL_Libretro *lr)
	Gets the default set of valid extensions associated with the core, seperated by a "\|".

void	SDL_Libretro_HandleEvent (SDL_Libretro lr, const SDL_Event event)
	Call this function within the SDL_PollEvent() loop to ensure libretro knows of important events.

bool	SDL_Libretro_InitConfig (SDL_Libretro lr, const char org, const char *app)
	Sets up the config file to be the default path, accoring to the organization and app name.

bool	SDL_Libretro_InitConfigFile (SDL_Libretro lr, const char file)
	Initializes the config system based on the given file.

bool	SDL_Libretro_LoadCore (SDL_Libretro lr, const char corePath)
	Loads a libretro core.

bool	SDL_Libretro_LoadGame (SDL_Libretro lr, const char gamePath)
	Loads a game at the given path.

bool	SDL_Libretro_LoadMemory (SDL_Libretro lr, unsigned memoryType, const char file)
	Load a core memory region from a file.

bool	SDL_Libretro_LoadMemory_IO (SDL_Libretro lr, unsigned memoryType, SDL_IOStream src, bool closeio)
	Load a core memory region from a stream.

bool	SDL_Libretro_LoadSRAM (SDL_Libretro lr, const char file)
	Loads the current SRAM to the given file.

bool	SDL_Libretro_LoadState (SDL_Libretro lr, const char file)
	Loads the libretro state from the given file.

bool	SDL_Libretro_Render (SDL_Renderer renderer, SDL_Libretro lr, const SDL_FRect *dstRect)
	Render the libretro context in the given renderer.

void	SDL_Libretro_ResetAllOptions (SDL_Libretro *lr)
	Reset every core option to its default value.

bool	SDL_Libretro_ResetOption (SDL_Libretro lr, const char key)
	Reset a core option to its default value.

bool	SDL_Libretro_SaveMemory (SDL_Libretro lr, unsigned memoryType, const char file)
	Write a core memory region to a file.

bool	SDL_Libretro_SaveMemory_IO (SDL_Libretro lr, unsigned memoryType, SDL_IOStream dst, bool closeio)
	Write a core memory region to a stream.

bool	SDL_Libretro_SaveSRAM (SDL_Libretro lr, const char file)
	Saves the current SRAM to the given file.

bool	SDL_Libretro_SaveState (SDL_Libretro lr, const char file)
	Saves the current libretro state to a file.

bool	SDL_Libretro_SaveState_IO (SDL_Libretro lr, SDL_IOStream dst, bool closeio)
	Save the current libretro state to the given SDL_IOStream.

void	SDL_Libretro_SetAudioLatency (SDL_Libretro *lr, unsigned latencyMs)
	Set the desired minimum audio latency for the audio stream.

bool	SDL_Libretro_SetCoreDirectory (SDL_Libretro lr, const char path)
	Sets the associated libretro core directory, where the default set of cores will be loaded from.

void	SDL_Libretro_SetFitMode (SDL_Libretro *lr, SDL_LibretroFitMode mode)
	Sets the desired scale mode for the libretro context when it's displayed.

void	SDL_Libretro_SetLogLevel (SDL_Libretro *lr, SDL_LogPriority level)
	Sets the threshold for logs to be posted.

bool	SDL_Libretro_SetMemoryData (SDL_Libretro lr, unsigned memoryType, const void data, size_t size)
	Overwrite a core memory region with caller-provided bytes.

void	SDL_Libretro_SetMessage (SDL_Libretro lr, const char msg, double duration)
	Add a message to be displayed within the libretro context.

bool	SDL_Libretro_SetOptionValue (SDL_Libretro lr, const char key, const char *value)
	Set a core option's value; fails if the value isn't one the core declared.

bool	SDL_Libretro_SetRenderer (SDL_Libretro lr, SDL_Renderer renderer)
	Set the renderer the libretro context draws into.

bool	SDL_Libretro_SetRewindEnabled (SDL_Libretro *lr, bool enabled, unsigned bufferFrames, unsigned captureInterval)
	Enable or disable the rewind system.

bool	SDL_Libretro_SetRewindMemoryDuration (SDL_Libretro *lr, double seconds)
	Set the rewind memory budget by target duration instead of raw bytes.

void	SDL_Libretro_SetRewindMemoryLimit (SDL_Libretro *lr, size_t maxBytes)
	Set the maximum number of bytes of encoded delta history to retain.

void	SDL_Libretro_SetVolume (SDL_Libretro *lr, float volume)
	Set the audio volume when playing sounds.

bool	SDL_Libretro_ShouldQuit (const SDL_Libretro *lr)
	Indicates whether or not the core has requested to shutdown.

void	SDL_Libretro_UnloadCore (SDL_Libretro *lr)
	Unloads the actively loaded core.

void	SDL_Libretro_UnloadGame (SDL_Libretro *lr)
	Unloads the actively loaded game.

Detailed Description

Macro Definition Documentation

◆ SDL_LIBRETRO_MAJOR_VERSION

#define SDL_LIBRETRO_MAJOR_VERSION 0

The major version of SDL_Libretro.

See also: SDL_LIBRETRO_VERSION; SDL_LIBRETRO_VERSION_ATLEAST

Definition at line 52 of file SDL_libretro.h.

◆ SDL_LIBRETRO_MICRO_VERSION

#define SDL_LIBRETRO_MICRO_VERSION 0

The micro/patch version of SDL_Libretro.

See also: SDL_LIBRETRO_VERSION; SDL_LIBRETRO_VERSION_ATLEAST

Definition at line 68 of file SDL_libretro.h.

◆ SDL_LIBRETRO_MINOR_VERSION

#define SDL_LIBRETRO_MINOR_VERSION 1

The minor version of SDL_Libretro.

See also: SDL_LIBRETRO_VERSION; SDL_LIBRETRO_VERSION_ATLEAST

Definition at line 60 of file SDL_libretro.h.

Enumeration Type Documentation

◆ SDL_LibretroFitMode

enum SDL_LibretroFitMode

When rendering the libretro context, determine how to display within the destination.

Enumerator
SDL_LIBRETRO_FIT_INTEGER	Keep the same aspect ratio, and fit within the confines of the destination.
SDL_LIBRETRO_FIT_STRETCH	Keep the same aspect ratio, while keeping integer scaling within the confines of the destination.

Definition at line 85 of file SDL_libretro.h.

Function Documentation

◆ SDL_Libretro_Create()

SDL_Libretro * SDL_Libretro_Create ( void )

Builds a libretro context.

See also: SDL_Libretro_LoadCore()

Definition at line 24 of file SDL_libretro_core.h.

References SDL_LIBRETRO_REWIND_DEFAULT_MAX_BYTES, and SDL_Libretro_SetVolume().

◆ SDL_Libretro_CreateSurface()

SDL_Surface * SDL_Libretro_CreateSurface ( const SDL_Libretro * lr )

Creates a new surface from the current libretro context.

The Surface must be destroyed after use with SDL_DestroySurface().

Definition at line 192 of file SDL_libretro_video.h.

◆ SDL_Libretro_Destroy()

void SDL_Libretro_Destroy ( SDL_Libretro * lr )

Destroys the given libretro context.

Will also unload the active game and core if needed.

Definition at line 64 of file SDL_libretro_core.h.

References SDL_Libretro_UnloadCore(), and SDL_Libretro_UnloadGame().

◆ SDL_Libretro_GetContentExtension()

const char * SDL_Libretro_GetContentExtension ( const SDL_Libretro * lr )

Get the extension of the loaded content, as it appears in the path.

Returns the text after the last '.' of the content path, in its original case (e.g. "SFC" for "game.SFC"), or "" when no content is loaded or the file has no extension. Note this is the raw-case extension; the lower-cased form handed to cores via GET_GAME_INFO_EXT (gameInfoExt.ext) may differ.

Parameters

lr	the libretro context.

Returns: the content extension (no leading dot), or "" if none.

Definition at line 995 of file SDL_libretro_core.h.

Referenced by SDL_Libretro_LoadGame().

◆ SDL_Libretro_GetFileName()

size_t SDL_Libretro_GetFileName	(	char *	dst,
		size_t	dstSize,
		const char *	path,
		bool	withExtension
	)

Copy the file name portion of a path into a caller-provided buffer.

The leading directory components and (optionally) the trailing extension are stripped. Useful for deriving save/state file names from a content path.

Parameters

dst	the destination buffer to fill (always null-terminated).
dstSize	the size of `dst` in bytes.
path	the source path, may be NULL.
withExtension	if true, keep the file extension; if false, strip it.

Returns: the length of the resulting string in dst, excluding the null terminator (0 on invalid arguments).

Definition at line 258 of file SDL_libretro_core.h.

Referenced by SDL_Libretro_LoadGame().

◆ SDL_Libretro_GetInputDescriptor()

bool SDL_Libretro_GetInputDescriptor	(	const SDL_Libretro *	lr,
		unsigned	index,
		unsigned *	port,
		unsigned *	device,
		unsigned *	id,
		const char **	description
	)

Retrieve an input descriptor by index.

This function can be used to enumerate all available input descriptors by calling it with incrementing index values starting at 0 until no descriptor is returned or an error is indicated.

Parameters

	lr	The libretro context.
[in]	index	Zero-based index of the input descriptor to retrieve. The value should start at 0 and be incremented to enumerate successive descriptors.
[out]	port	Zero-based port number to query (e.g., controller port).
[out]	device	Device identifier within the port (if applicable).
[out]	id	The ID of the descriptor.
[out]	description	The description of the input device.

Returns: 0 on success, a negative error code on failure.

Note: The contents written to out_desc are owned by the caller after the call returns and may be modified or freed as appropriate by the caller.

See also: retro_input_descriptor

Definition at line 605 of file SDL_libretro_input.h.

◆ SDL_Libretro_GetInputDescriptorCount()

unsigned SDL_Libretro_GetInputDescriptorCount ( const SDL_Libretro * lr )

Retrieve the number of input descriptors provided by a Libretro core.

Parameters

lr	Pointer to an initialized SDL_Libretro instance. Must not be NULL.

See also: SDL_Libretro_GetInputDescriptor()

Definition at line 583 of file SDL_libretro_input.h.

◆ SDL_Libretro_GetMapAddress()

void * SDL_Libretro_GetMapAddress	(	const SDL_Libretro *	lr,
		size_t	address,
		size_t *	regionRemaining
	)

Translate an emulated (guest) address to a live host pointer via the memory map.

Walks the descriptors published by the core (RETRO_ENVIRONMENT_SET_MEMORY_MAPS) and returns a pointer into the core's live memory for address, so debuggers, cheat finders, and RAM watchers don't have to reimplement the descriptor math.

Resolves an address that lies within a descriptor's primary mapped range ([start, start + len), after folding out disconnect bits). Mirror/aliased addresses that rely on a descriptor's select mask to wrap back into the region may return NULL rather than a guess; the result is always either a correct pointer or NULL, never a wrong one.

Parameters

lr	the libretro context.
address	the emulated address to resolve.
regionRemaining	if non-NULL, receives the number of contiguous bytes from `address` to the end of the matched region (0 when unmatched).

Returns: a host pointer into the core's live memory, or NULL if no descriptor maps the address (or no core/game/map is present). Do not free it.

See also: SDL_Libretro_GetMemoryMapDescriptor(); RETRO_ENVIRONMENT_SET_MEMORY_MAPS

Definition at line 272 of file SDL_libretro_serialize.h.

◆ SDL_Libretro_GetMemoryData()

void * SDL_Libretro_GetMemoryData	(	const SDL_Libretro *	lr,
		unsigned	memoryType,
		size_t *	size
	)

Get a pointer to a core memory region and its size.

Returns the core's live buffer for the given RETRO_MEMORY_* type. The pointer is owned by the core: do not free it, it stays valid until the core is unloaded, and writing through it pokes the running game directly. Must not be called concurrently with SDL_Libretro_Update().

Parameters

lr	the libretro context.
memoryType	one of the RETRO_MEMORY_* constants.
size	receives the region size in bytes (set to 0 when unavailable), or NULL.

Returns: the live region pointer, or NULL if the core exposes no such memory.

See also: SDL_Libretro_SetMemoryData()

Definition at line 139 of file SDL_libretro_serialize.h.

Referenced by SDL_Libretro_LoadMemory_IO(), SDL_Libretro_SaveMemory(), SDL_Libretro_SaveMemory_IO(), and SDL_Libretro_SetMemoryData().

◆ SDL_Libretro_GetMemoryMapCount()

unsigned SDL_Libretro_GetMemoryMapCount ( const SDL_Libretro * lr )

Get the number of memory-map descriptors the core has published.

Cores describe their address space via RETRO_ENVIRONMENT_SET_MEMORY_MAPS for the benefit of debuggers, cheat finders, and achievement runtimes. Returns 0 if the core published no map.

Parameters

lr	the libretro context.

Returns: the descriptor count.

See also: SDL_Libretro_GetMemoryMapDescriptor(); RETRO_ENVIRONMENT_SET_MEMORY_MAPS

Definition at line 207 of file SDL_libretro_serialize.h.

◆ SDL_Libretro_GetMemoryMapDescriptor()

bool SDL_Libretro_GetMemoryMapDescriptor	(	const SDL_Libretro *	lr,
		unsigned	index,
		Uint64 *	flags,
		void **	ptr,
		size_t *	offset,
		size_t *	start,
		size_t *	select,
		size_t *	disconnect,
		size_t *	len,
		const char **	addrspace
	)

Retrieve one memory-map descriptor by index.

Maps a region of the emulated address space onto a host pointer. To translate a guest address that falls in this descriptor to a host pointer:

host = (Uint8*)ptr + offset + ((guest & ~disconnect) - start)

Any out-parameter may be NULL if not needed. The returned ptr and addrspace are owned by the context and remain valid until the core is unloaded; do not free them.

Parameters

lr	the libretro context.
index	the descriptor index, in [0, SDL_Libretro_GetMemoryMapCount()).
flags	receives the RETRO_MEMDESC_* flag bits, or NULL.
ptr	receives the host base pointer of the region, or NULL.
offset	receives the offset from `ptr` to the region start, or NULL.
start	receives the first emulated address mapped here, or NULL.
select	receives the address-decode select mask, or NULL.
disconnect	receives the disconnect (ignored-bits) mask, or NULL.
len	receives the region length in bytes, or NULL.
addrspace	receives the address-space label (may be NULL itself), or NULL.

Returns: true on success, false if the index is out of range or no core is loaded.

Definition at line 232 of file SDL_libretro_serialize.h.

◆ SDL_Libretro_GetOptionValueLabel()

const char * SDL_Libretro_GetOptionValueLabel	(	SDL_Libretro *	lr,
		const char *	key
	)

Get the human-readable label for a core option's current value.

Falls back to the raw value when the core supplied no label, like in core option variables API version 0 or 1.

Definition at line 211 of file SDL_libretro_options.h.

References SDL_LibretroOptionValue::label, SDL_Libretro_GetOption(), SDL_LibretroOption::value, SDL_LibretroOption::values, and SDL_LibretroOption::valuesCount.

◆ SDL_Libretro_GetPerformanceLevel()

unsigned SDL_Libretro_GetPerformanceLevel ( const SDL_Libretro * lr )

Get the performance level the core requested via SET_PERFORMANCE_LEVEL.

Parameters

lr	the libretro context.

Returns: the requested performance level, or 0 if none/invalid.

See also: RETRO_ENVIRONMENT_SET_PERFORMANCE_LEVEL

Definition at line 983 of file SDL_libretro_core.h.

◆ SDL_Libretro_GetPortDevice()

unsigned SDL_Libretro_GetPortDevice	(	const SDL_Libretro *	lr,
		unsigned	port
	)

Get the device type assigned to a controller port.

Returns the RETRO_DEVICE_* type last set via SDL_Libretro_SetPortDevice(), or RETRO_DEVICE_NONE if none was set or the arguments are invalid.

Parameters

lr	the libretro context.
port	the controller port, in [0, 16).

Returns: the assigned RETRO_DEVICE_* type, or RETRO_DEVICE_NONE.

Definition at line 559 of file SDL_libretro_input.h.

◆ SDL_Libretro_GetRenderer()

SDL_Renderer * SDL_Libretro_GetRenderer ( const SDL_Libretro * lr )

Get the renderer the context draws into.

Parameters

lr	the libretro context.

Returns: the renderer set via SDL_Libretro_SetRenderer(), or NULL if none.

Definition at line 179 of file SDL_libretro_video.h.

◆ SDL_Libretro_GetRewindEnabled()

bool SDL_Libretro_GetRewindEnabled ( const SDL_Libretro * lr )

Check whether the rewind system is enabled (independent of current direction).

Parameters

lr	the libretro context.

Returns: true if rewind capture is enabled.

Definition at line 718 of file SDL_libretro_serialize.h.

◆ SDL_Libretro_GetRewindMemoryLimit()

size_t SDL_Libretro_GetRewindMemoryLimit ( const SDL_Libretro * lr )

Get the current rewind memory budget in bytes (0 if unbounded).

Parameters

lr	the libretro context.

Returns: the byte budget, or 0 if unbounded.

Definition at line 775 of file SDL_libretro_serialize.h.

◆ SDL_Libretro_GetRewindMemoryUsage()

size_t SDL_Libretro_GetRewindMemoryUsage ( const SDL_Libretro * lr )

Get the approximate memory currently held by the rewind buffer, in bytes.

Includes the encoded delta history plus the fixed reference/scratch buffers and the entry table. Useful for debug overlays and tuning the memory limit.

Parameters

lr	the libretro context.

Returns: total bytes held by the rewind subsystem, or 0 if disabled.

See also: SDL_Libretro_SetRewindMemoryLimit()

Definition at line 743 of file SDL_libretro_serialize.h.

◆ SDL_Libretro_GetRewindRemaining()

double SDL_Libretro_GetRewindRemaining ( const SDL_Libretro * lr )

Calculates the amount of rewind time remaining in the buffer.

Parameters

lr	the libretro context.

Returns: seconds of gameplay that can still be rewound, or 0.0 if rewind is disabled or the buffer is empty.

Definition at line 728 of file SDL_libretro_serialize.h.

◆ SDL_Libretro_GetSavePath()

size_t SDL_Libretro_GetSavePath	(	const SDL_Libretro *	lr,
		const char *	extension,
		char *	dst,
		size_t	dstSize
	)

Build a path in the save directory for the currently loaded content.

Produces "<saveDirectory>/<contentName><extension>" (or just "<contentName><extension>" when no save directory is set). Handy for deriving SRAM (".srm"), RTC (".rtc"), or save-state file names without hardcoding them.

Parameters

lr	the libretro context.
extension	the extension to append, including the dot (NULL or "" for none).
dst	the destination buffer (always null-terminated when dstSize > 0).
dstSize	the size of `dst` in bytes.

Returns: the length of the resulting string, or 0 if no content is loaded or on invalid arguments.

Definition at line 289 of file SDL_libretro_core.h.

◆ SDL_Libretro_InitConfig()

bool SDL_Libretro_InitConfig	(	SDL_Libretro *	lr,
		const char *	org,
		const char *	app
	)

Sets up the config file to be the default path, accoring to the organization and app name.

Will automatically call SDL_Libretro_CloseConfig()

See also: SDL_Libretro_InitConfigFile; SDL_GetPrefPath(); https://wiki.libsdl.org/SDL3/SDL_GetPrefPath

Definition at line 80 of file SDL_libretro_config.h.

References SDL_Libretro_InitConfigFile().

◆ SDL_Libretro_InitConfigFile()

bool SDL_Libretro_InitConfigFile	(	SDL_Libretro *	lr,
		const char *	file
	)

Initializes the config system based on the given file.

Will load the configuration from the file, and save it when destroying the instance.

See also: SDL_Libretro_InitConfig()

Definition at line 26 of file SDL_libretro_config.h.

References SDL_Libretro_SetAudioLatency(), SDL_Libretro_SetCoreDirectory(), SDL_Libretro_SetFitMode(), and SDL_Libretro_SetVolume().

Referenced by SDL_Libretro_InitConfig().

◆ SDL_Libretro_LoadCore()

bool SDL_Libretro_LoadCore	(	SDL_Libretro *	lr,
		const char *	corePath
	)

Loads a libretro core.

Parameters

lr	the libretro context.
corePath	Either the path to the core to load, or a name of the core within the core directory.

See also: SDL_Libretro_Create(); SDL_Libretro_UnloadCore()

Definition at line 113 of file SDL_libretro_core.h.

References SDL_Libretro_UnloadCore().

◆ SDL_Libretro_LoadGame()

bool SDL_Libretro_LoadGame	(	SDL_Libretro *	lr,
		const char *	gamePath
	)

Loads a game at the given path.

A renderer is not required to load a game. If none has been set via SDL_Libretro_SetRenderer(), the game still loads and runs (audio and input work); video texture creation is deferred until a renderer is set, and until then rendered frames are dropped.

See also: SDL_Libretro_UnloadGame(); SDL_Libretro_SetRenderer()

Definition at line 424 of file SDL_libretro_core.h.

References SDL_Libretro_GetContentExtension(), SDL_Libretro_GetFileName(), SDL_Libretro_SetRewindEnabled(), and SDL_Libretro_UnloadGame().

◆ SDL_Libretro_LoadMemory()

bool SDL_Libretro_LoadMemory	(	SDL_Libretro *	lr,
		unsigned	memoryType,
		const char *	file
	)

Load a core memory region from a file.

Convenience wrapper over SDL_Libretro_LoadMemory_IO().

Parameters

lr	the libretro context.
memoryType	one of the RETRO_MEMORY_* constants.
file	the source file path.

Returns: true on success, false on error.

Definition at line 431 of file SDL_libretro_serialize.h.

References SDL_Libretro_LoadMemory_IO().

Referenced by SDL_Libretro_LoadSRAM().

◆ SDL_Libretro_LoadMemory_IO()

bool SDL_Libretro_LoadMemory_IO	(	SDL_Libretro *	lr,
		unsigned	memoryType,
		SDL_IOStream *	src,
		bool	closeio
	)

Load a core memory region from a stream.

Copies stream contents into the live memory region for the given type. When the stream and the region differ in size, only the overlapping bytes are copied, so a save from a slightly different revision still loads what it can.

Parameters

lr	the libretro context.
memoryType	one of the RETRO_MEMORY_* constants.
src	the source stream.
closeio	if true, close `src` before returning (even on failure).

Returns: true on success, false if the core exposes no such memory, on a read error, or on invalid arguments.

Definition at line 388 of file SDL_libretro_serialize.h.

References SDL_Libretro_GetMemoryData(), and SDL_Libretro_SetMemoryData().

Referenced by SDL_Libretro_LoadMemory().

◆ SDL_Libretro_Render()

bool SDL_Libretro_Render	(	SDL_Renderer *	renderer,
		SDL_Libretro *	lr,
		const SDL_FRect *	dstRect
	)

Render the libretro context in the given renderer.

Parameters

renderer	the renderer to draw into; must not be NULL.
lr	the libretro context.
dstRect	the destination rectangle, or NULL to fit within the full width and height of the renderer.

Returns: true on success, false on invalid arguments or if there is nothing to draw yet.

See also: SDL_Libretro_SetRenderer()

Definition at line 268 of file SDL_libretro_video.h.

References SDL_Libretro_SetRenderer().

◆ SDL_Libretro_SaveMemory()

bool SDL_Libretro_SaveMemory	(	SDL_Libretro *	lr,
		unsigned	memoryType,
		const char *	file
	)

Write a core memory region to a file.

Convenience wrapper over SDL_Libretro_SaveMemory_IO(). No file is created when the core exposes no such memory region.

Parameters

lr	the libretro context.
memoryType	one of the RETRO_MEMORY_* constants.
file	the destination file path.

Returns: true on success, false on error.

Definition at line 353 of file SDL_libretro_serialize.h.

References SDL_Libretro_GetMemoryData(), and SDL_Libretro_SaveMemory_IO().

Referenced by SDL_Libretro_SaveSRAM().

◆ SDL_Libretro_SaveMemory_IO()

bool SDL_Libretro_SaveMemory_IO	(	SDL_Libretro *	lr,
		unsigned	memoryType,
		SDL_IOStream *	dst,
		bool	closeio
	)

Write a core memory region to a stream.

Persists the live contents of the given libretro memory type (e.g. RETRO_MEMORY_SAVE_RAM for battery saves, RETRO_MEMORY_RTC for a real-time clock). A core that exposes no such region is treated as success with nothing written, so callers don't have to special-case it.

Parameters

lr	the libretro context.
memoryType	one of the RETRO_MEMORY_* constants.
dst	the destination stream.
closeio	if true, close `dst` before returning (even on failure).

Returns: true on success (including "core has no such memory"), false on a write error or invalid arguments.

Definition at line 325 of file SDL_libretro_serialize.h.

References SDL_Libretro_GetMemoryData().

Referenced by SDL_Libretro_SaveMemory().

◆ SDL_Libretro_SetAudioLatency()

void SDL_Libretro_SetAudioLatency	(	SDL_Libretro *	lr,
		unsigned	latencyMs
	)

Set the desired minimum audio latency for the audio stream.

See also: SDL_LIBRETRO_AUDIO_DEFAULT_LATENCY_MS

Definition at line 260 of file SDL_libretro_audio.h.

Referenced by SDL_Libretro_InitConfigFile().

◆ SDL_Libretro_SetLogLevel()

void SDL_Libretro_SetLogLevel	(	SDL_Libretro *	lr,
		SDL_LogPriority	level
	)

Sets the threshold for logs to be posted.

See also: SDL_LOG_PRIORITY_INVALID

Definition at line 929 of file SDL_libretro_core.h.

◆ SDL_Libretro_SetMemoryData()

bool SDL_Libretro_SetMemoryData	(	SDL_Libretro *	lr,
		unsigned	memoryType,
		const void *	data,
		size_t	size
	)

Overwrite a core memory region with caller-provided bytes.

Copies up to the region's capacity; any extra bytes are ignored. Writes to the core's live memory, so it must not race SDL_Libretro_Update().

Parameters

lr	the libretro context.
memoryType	one of the RETRO_MEMORY_* constants.
data	the source bytes.
size	the number of bytes available in `data`.

Returns: true on success, false on invalid arguments or if the core exposes no such memory.

See also: SDL_Libretro_GetMemoryData()

Definition at line 162 of file SDL_libretro_serialize.h.

References SDL_Libretro_GetMemoryData().

Referenced by SDL_Libretro_LoadMemory_IO().

◆ SDL_Libretro_SetRenderer()

bool SDL_Libretro_SetRenderer	(	SDL_Libretro *	lr,
		SDL_Renderer *	renderer
	)

Set the renderer the libretro context draws into.

If a game is already loaded, setting the renderer builds the video texture immediately.

Parameters

lr	the libretro context.
renderer	the renderer to draw into; must not be NULL.

Returns: true on success, false on invalid arguments or if the texture (re)build fails.

Definition at line 152 of file SDL_libretro_video.h.

Referenced by SDL_Libretro_Render().

◆ SDL_Libretro_SetRewindEnabled()

bool SDL_Libretro_SetRewindEnabled	(	SDL_Libretro *	lr,
		bool	enabled,
		unsigned	bufferFrames,
		unsigned	captureInterval
	)

Enable or disable the rewind system.

When enabled, a circular buffer of serialized core states is maintained so that setting a negative speed (via SDL_Libretro_SetSpeed()) rewinds gameplay. The buffer is allocated lazily once a game is loaded and the core's serialize size is known.

History is bounded by two independent limits: the snapshot count (bufferFrames) and the delta memory budget (see SDL_Libretro_SetRewindMemoryLimit(), which defaults to SDL_LIBRETRO_REWIND_DEFAULT_MAX_BYTES at context creation). Whichever is reached first caps the rewind depth. This call does not change the memory budget, a budget you set beforehand, including 0 (unbounded), is preserved.

Enable SDL_LIBRETRO_ENABLE_REWIND_DELTA to use the XOR compression between frames to reduce memory at the expense of performance.

Parameters

lr	the libretro context.
enabled	true to enable, false to disable.
bufferFrames	maximum number of state snapshots to keep (0 for a sensible default of 300, roughly 5 seconds at 60 fps).
captureInterval	capture a snapshot every N frames (0 for the default of 1, i.e. every frame). Provide a larger number in order to allow a longer rewind duration.

Returns: true on success, false on allocation failure or if the core does not support serialization.

See also: SDL_Libretro_SetRewindMemoryLimit()

Definition at line 637 of file SDL_libretro_serialize.h.

Referenced by SDL_Libretro_LoadGame().

◆ SDL_Libretro_SetRewindMemoryDuration()

bool SDL_Libretro_SetRewindMemoryDuration	(	SDL_Libretro *	lr,
		double	seconds
	)

Set the rewind memory budget by target duration instead of raw bytes.

Computes the worst-case bytes needed to retain seconds of rewindable gameplay and forwards it to SDL_Libretro_SetRewindMemoryLimit(). The estimate is the number of snapshots that span the duration (the core's frame rate divided by the capture interval, times seconds) multiplied by the per-snapshot state size. With delta compression enabled (SDL_LIBRETRO_ENABLE_REWIND_DELTA) snapshots usually store far less than the full state, so this is a conservative upper bound that will typically hold longer than requested.

The snapshot count (bufferFrames in SDL_Libretro_SetRewindEnabled()) is an independent limit; if it is smaller than the duration requires, it, not the byte budget, will cap the achievable rewind depth.

Requires the core's serialize size to be known, so a core must be loaded (or rewind already enabled with a game loaded). Roughly the inverse of SDL_Libretro_GetRewindRemaining().

Parameters

lr	the libretro context.
seconds	the desired rewind duration in seconds (must be positive).

Returns: true on success, false if lr or seconds is invalid or the core's serialize size is not yet available.

See also: SDL_Libretro_SetRewindEnabled(); SDL_Libretro_SetRewindMemoryLimit(); SDL_Libretro_GetRewindRemaining()

Definition at line 795 of file SDL_libretro_serialize.h.

References SDL_Libretro_SetRewindMemoryLimit().

◆ SDL_Libretro_SetRewindMemoryLimit()

void SDL_Libretro_SetRewindMemoryLimit	(	SDL_Libretro *	lr,
		size_t	maxBytes
	)

Set the maximum number of bytes of encoded delta history to retain.

When the stored history exceeds this budget the oldest snapshots are dropped until it fits (the most recent snapshot is always kept), trading rewind duration for bounded memory. Applies immediately. Pass 0 to remove the byte limit and rely solely on the frame-count capacity.

The budget defaults to SDL_LIBRETRO_REWIND_DEFAULT_MAX_BYTES at context creation. Whatever value is set here, including 0 (unbounded), persists across SDL_Libretro_SetRewindEnabled() calls.

Parameters

lr	the libretro context.
maxBytes	the budget in bytes, or 0 for unbounded.

See also: SDL_Libretro_SetRewindEnabled()

Definition at line 763 of file SDL_libretro_serialize.h.

Referenced by SDL_Libretro_SetRewindMemoryDuration().

◆ SDL_Libretro_ShouldQuit()

bool SDL_Libretro_ShouldQuit ( const SDL_Libretro * lr )

Indicates whether or not the core has requested to shutdown.

See also: RETRO_ENVIRONMENT_SHUTDOWN

Definition at line 726 of file SDL_libretro_core.h.

◆ SDL_Libretro_UnloadCore()

void SDL_Libretro_UnloadCore ( SDL_Libretro * lr )

Unloads the actively loaded core.

Will also unload the game if it's still loaded.

See also: SD_Libretro_UnloadGame()

Definition at line 212 of file SDL_libretro_core.h.

References SDL_Libretro_UnloadGame().

Referenced by SDL_Libretro_Destroy(), and SDL_Libretro_LoadCore().

◆ SDL_Libretro_UnloadGame()

void SDL_Libretro_UnloadGame ( SDL_Libretro * lr )

Unloads the actively loaded game.

See also: SD_Libretro_UnloadCore()

Definition at line 559 of file SDL_libretro_core.h.

Referenced by SDL_Libretro_Destroy(), SDL_Libretro_LoadGame(), and SDL_Libretro_UnloadCore().

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SDL_LIBRETRO_MAJOR_VERSION

◆ SDL_LIBRETRO_MICRO_VERSION

◆ SDL_LIBRETRO_MINOR_VERSION

Enumeration Type Documentation

◆ SDL_LibretroFitMode

Function Documentation

◆ SDL_Libretro_Create()

◆ SDL_Libretro_CreateSurface()

◆ SDL_Libretro_Destroy()

◆ SDL_Libretro_GetContentExtension()

◆ SDL_Libretro_GetFileName()

◆ SDL_Libretro_GetInputDescriptor()

◆ SDL_Libretro_GetInputDescriptorCount()

◆ SDL_Libretro_GetMapAddress()

◆ SDL_Libretro_GetMemoryData()

◆ SDL_Libretro_GetMemoryMapCount()

◆ SDL_Libretro_GetMemoryMapDescriptor()

◆ SDL_Libretro_GetOptionValueLabel()

◆ SDL_Libretro_GetPerformanceLevel()

◆ SDL_Libretro_GetPortDevice()

◆ SDL_Libretro_GetRenderer()

◆ SDL_Libretro_GetRewindEnabled()

◆ SDL_Libretro_GetRewindMemoryLimit()

◆ SDL_Libretro_GetRewindMemoryUsage()

◆ SDL_Libretro_GetRewindRemaining()

◆ SDL_Libretro_GetSavePath()

◆ SDL_Libretro_InitConfig()

◆ SDL_Libretro_InitConfigFile()

◆ SDL_Libretro_LoadCore()

◆ SDL_Libretro_LoadGame()

◆ SDL_Libretro_LoadMemory()

◆ SDL_Libretro_LoadMemory_IO()

◆ SDL_Libretro_Render()

◆ SDL_Libretro_SaveMemory()

◆ SDL_Libretro_SaveMemory_IO()

◆ SDL_Libretro_SetAudioLatency()

◆ SDL_Libretro_SetLogLevel()

◆ SDL_Libretro_SetMemoryData()

◆ SDL_Libretro_SetRenderer()

◆ SDL_Libretro_SetRewindEnabled()

◆ SDL_Libretro_SetRewindMemoryDuration()

◆ SDL_Libretro_SetRewindMemoryLimit()

◆ SDL_Libretro_ShouldQuit()

◆ SDL_Libretro_UnloadCore()

◆ SDL_Libretro_UnloadGame()