SDL_libretro_serialize.h File Reference

SDL_libretro - save states, core memory (SRAM/RTC/...), and rewind. More...

Go to the source code of this file.

Macros
#define	SDL_LIBRETRO_ENABLE_REWIND_DELTA
	Compile-time switch that enables the delta compression for the rewind buffer.
#define	SDL_LIBRETRO_REWIND_DEFAULT_MAX_BYTES   ((size_t)256 * 1024 * 1024)
	Default ceiling on the encoded rewind history (delta data only), in bytes.

Functions
bool	SDL_Libretro_AddDiskImage (SDL_Libretro *lr, const char *path)
	Appends a new disk image from a file path.
bool	SDL_Libretro_AddDiskImage_IO (SDL_Libretro *lr, SDL_IOStream *src, const char *path, bool closeio)
	Appends a new disk image from an SDL_IOStream.
bool	SDL_Libretro_EjectDisk (SDL_Libretro *lr)
	Ejects the disk tray, allowing the disk image to be changed.
unsigned	SDL_Libretro_GetDiskCount (const SDL_Libretro *lr)
	Returns the number of disk images available to the loaded core.
unsigned	SDL_Libretro_GetDiskIndex (const SDL_Libretro *lr)
	Returns the index of the currently inserted disk image.
bool	SDL_Libretro_GetDiskLabel (const SDL_Libretro *lr, unsigned index, char *label, size_t len)
	Retrieves the human-readable label of a disk image.
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.
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.
bool	SDL_Libretro_GetSRAMAutoSave (const SDL_Libretro *lr)
	Check whether SRAM is loaded and saved along with the game.
size_t	SDL_Libretro_GetStateSize (const SDL_Libretro *lr)
	Retrieves the size of serialized states.
bool	SDL_Libretro_InsertDisk (SDL_Libretro *lr)
	Closes the disk tray after a disk change.
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 SRAM from the given file.
bool	SDL_Libretro_LoadSRAM_IO (SDL_Libretro *lr, SDL_IOStream *src, bool closeio)
	Load the core's battery-backed save RAM from a stream.
bool	SDL_Libretro_LoadState (SDL_Libretro *lr, const char *file)
	Loads the libretro state from the given file.
bool	SDL_Libretro_LoadState_IO (SDL_Libretro *lr, SDL_IOStream *src, bool closeio)
	Load a libretro state from the given SDL_IOStream.
void	SDL_Libretro_ResetCheats (SDL_Libretro *lr)
	Clears all cheats that were set on the core.
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_SaveSRAM_IO (SDL_Libretro *lr, SDL_IOStream *dst, bool closeio)
	Write the core's battery-backed save RAM to a stream.
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.
bool	SDL_Libretro_SetCheat (SDL_Libretro *lr, unsigned index, bool enabled, const char *code)
	Set a cheat code either enabled or disabled within the libretro context.
bool	SDL_Libretro_SetDiskIndex (SDL_Libretro *lr, unsigned index)
	Sets the disk image index to insert into the emulated drive.
bool	SDL_Libretro_SetInitialDisk (SDL_Libretro *lr, unsigned index, const char *path)
	Sets the disk image to insert once content is loaded.
bool	SDL_Libretro_SetMemoryData (SDL_Libretro *lr, unsigned memoryType, const void *data, size_t size)
	Overwrite a core memory region with caller-provided bytes.
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_SetSRAMAutoSave (SDL_Libretro *lr, bool enabled)
	Load and save the core's battery-backed save RAM along with the game.

Detailed Description

SDL_libretro - save states, core memory (SRAM/RTC/...), and rewind.

Definition in file SDL_libretro_serialize.h.

Macro Definition Documentation

SDL_LIBRETRO_ENABLE_REWIND_DELTA

#define SDL_LIBRETRO_ENABLE_REWIND_DELTA

Compile-time switch that enables the delta compression for the rewind buffer.

Undefined by default, rewind stores each snapshot as a full serialized state, so capture is a single fixed-size copy and a step back is a single copy back. Define this before including the implementation to instead store an RLE-compressed XOR delta between consecutive states: a single full reference state is kept, each entry holds only the bytes that changed, and a step back XORs the delta into the reference to reconstruct the previous state.

This trades CPU for memory. Deltas dramatically shrink the per-frame footprint when little changes frame to frame (so the frame-count and byte-budget limits buy a far longer rewind window), at the cost of an encode pass on every capture and a decode pass on every step. For multi-megabyte states (e.g. PSX) that extra scan is the dominant capture cost, so leave it off when memory is ample and capture latency matters.

See also

SDL_Libretro_SetRewindEnabled()

SDL_LIBRETRO_REWIND_DEFAULT_MAX_BYTES

Definition at line 21 of file SDL_libretro_serialize.h.

SDL_LIBRETRO_REWIND_DEFAULT_MAX_BYTES

#define SDL_LIBRETRO_REWIND_DEFAULT_MAX_BYTES   ((size_t)256 * 1024 * 1024)

Default ceiling on the encoded rewind history (delta data only), in bytes.

Caps worst-case memory for cores with a large or incompressible serialize size, where the frame-count limit alone could otherwise grow the buffer to gigabytes. Override per build, or at runtime via SDL_Libretro_SetRewindMemoryLimit().

Definition at line 31 of file SDL_libretro_serialize.h.