SDL_libretro.h File Reference

SDL_libretro - SDL3 libretro frontend library. More...

Go to the source code of this file.

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_EVENT_LIBRETRO   (SDL_EVENT_USER + 0x1000)
	The base SDL event type for SDL_libretro events.
#define	SDL_EVENT_LIBRETRO_CORE_LOADED   (SDL_EVENT_LIBRETRO | 0xF00)
	A core finished loading; data2 is the core name, valid until the next load or unload.
#define	SDL_EVENT_LIBRETRO_CORE_UNLOADED   (SDL_EVENT_LIBRETRO | 0xF04)
	The core was unloaded, along with any game it ran.
#define	SDL_EVENT_LIBRETRO_ENVIRONMENT(cmd)   (SDL_EVENT_LIBRETRO | ((cmd) & 0x3FF) | (((cmd) >> 6) & 0xC00))
	The SDL event type a RETRO_ENVIRONMENT_* command arrives as, when SDL_libretro leaves the command to the application.
#define	SDL_EVENT_LIBRETRO_ENVIRONMENT_LAST   (SDL_EVENT_LIBRETRO | 0xBFF)
	The last SDL event type an environment command can arrive as.
#define	SDL_EVENT_LIBRETRO_GAME_LOADED   (SDL_EVENT_LIBRETRO | 0xF01)
	A game finished loading, whether directly or through the menu; data2 is the game name, valid until the next load or unload.
#define	SDL_EVENT_LIBRETRO_GAME_UNLOADED   (SDL_EVENT_LIBRETRO | 0xF05)
	The game was unloaded, whether directly or through the core unloading.
#define	SDL_EVENT_LIBRETRO_GEOMETRY_CHANGED   (SDL_EVENT_LIBRETRO | 0xF07)
	The video size, aspect ratio, or timing changed mid-game.
#define	SDL_EVENT_LIBRETRO_LAST   (SDL_EVENT_LIBRETRO | 0xFFF)
	The last SDL event type in the SDL_libretro range.
#define	SDL_EVENT_LIBRETRO_MENU_CLOSED   (SDL_EVENT_LIBRETRO | 0xF03)
	The menu was dismissed; the game resumes.
#define	SDL_EVENT_LIBRETRO_MENU_OPENED   (SDL_EVENT_LIBRETRO | 0xF02)
	The menu became visible; the game pauses.
#define	SDL_EVENT_LIBRETRO_SHUTDOWN   (SDL_EVENT_LIBRETRO | 0xF06)
	The core requested shutdown.
#define	SDL_LIBRETRO_ENVIRONMENT_COMMAND(type)   ((((type) - SDL_EVENT_LIBRETRO) & 0x3FF) | ((((type) - SDL_EVENT_LIBRETRO) & 0xC00) << 6))
	The RETRO_ENVIRONMENT_* command, flags included, that an environment event type stands for; the reverse of SDL_EVENT_LIBRETRO_ENVIRONMENT().
#define	SDL_LIBRETRO_MAJOR_VERSION   0
	The major version of SDL_Libretro.
#define	SDL_LIBRETRO_MAX_USERS   4
	The number of controller ports (gamepads) the frontend tracks.
#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_Libretro	SDL_Libretro
	A libretro frontend context: one loaded core, its game, and the settings that carry across cores.
typedef enum SDL_LibretroAnalogToDigital	SDL_LibretroAnalogToDigital
	Which analog stick, if any, also registers D-Pad presses for a controller port.
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_LibretroMenu	SDL_LibretroMenu
	An in-app menu built on nuklear_console.
typedef void(*	SDL_LibretroMenuCallback) (SDL_LibretroMenu *menu, void *userdata)
	A callback for menu entries added by the application.
typedef enum SDL_LibretroMenuStyle	SDL_LibretroMenuStyle
	Color themes for the menu.
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_LibretroAnalogToDigital { SDL_LIBRETRO_ANALOG_TO_DIGITAL_NONE = 0 , SDL_LIBRETRO_ANALOG_TO_DIGITAL_LEFT = 1 , SDL_LIBRETRO_ANALOG_TO_DIGITAL_RIGHT = 2 , SDL_LIBRETRO_ANALOG_TO_DIGITAL_COUNT = 3 }
	Which analog stick, if any, also registers D-Pad presses for a controller port. More...
enum	SDL_LibretroFitMode {   SDL_LIBRETRO_FIT_FIRST = 0 , SDL_LIBRETRO_FIT_ASPECT = 0 , SDL_LIBRETRO_FIT_INTEGER = 1 , SDL_LIBRETRO_FIT_STRETCH = 2 ,   SDL_LIBRETRO_FIT_COUNT = 3 }
	When rendering the libretro context, determine how to display within the destination. More...
enum	SDL_LibretroMenuStyle {   SDL_LIBRETRO_MENU_STYLE_CATPPUCCIN_MOCHA = 0 , SDL_LIBRETRO_MENU_STYLE_CATPPUCCIN_LATTE , SDL_LIBRETRO_MENU_STYLE_CATPPUCCIN_FRAPPE , SDL_LIBRETRO_MENU_STYLE_CATPPUCCIN_MACCHIATO ,   SDL_LIBRETRO_MENU_STYLE_DRACULA , SDL_LIBRETRO_MENU_STYLE_DARK , SDL_LIBRETRO_MENU_STYLE_COUNT }
	Color themes for the menu. More...

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_AddMenuButton (SDL_LibretroMenu *menu, const char *label, SDL_LibretroMenuCallback callback, void *userdata)
	Adds a button to the main menu, just above Quit.
bool	SDL_Libretro_AddMenuCheckbox (SDL_LibretroMenu *menu, const char *label, bool *value, SDL_LibretroMenuCallback callback, void *userdata)
	Adds a checkbox to the main menu, just above Quit.
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)
	Creates a new libretro context.
SDL_LibretroMenu *	SDL_Libretro_CreateMenu (SDL_Libretro *lr)
	Creates the in-app menu for 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.
void	SDL_Libretro_DestroyMenu (SDL_LibretroMenu *menu)
	Destroys a menu created with SDL_Libretro_CreateMenu().
bool	SDL_Libretro_EjectDisk (SDL_Libretro *lr)
	Ejects the disk tray, allowing the disk image to be changed.
SDL_LibretroAnalogToDigital	SDL_Libretro_GetAnalogToDigital (const SDL_Libretro *lr, unsigned port)
	Get the analog stick that also registers D-Pad presses on a controller port.
float	SDL_Libretro_GetAspectRatio (const SDL_Libretro *lr)
	Gets the aspect ratio for the libretro context.
unsigned	SDL_Libretro_GetAudioLatency (const SDL_Libretro *lr)
	Get the minimum audio latency for the audio stream.
bool	SDL_Libretro_GetBlockExtract (const SDL_Libretro *lr)
	Retrieves whether the core expects archives to be loaded directly.
const SDL_LibretroCategory *	SDL_Libretro_GetCategory (const SDL_Libretro *lr, const char *key)
	Retrieve an option category by key.
const SDL_LibretroCategory *	SDL_Libretro_GetCategoryByIndex (const SDL_Libretro *lr, unsigned index)
	Retrieve an option category by index.
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_GetCoreAssetsDirectory (SDL_Libretro *lr)
	Get the core assets directory.
const char *	SDL_Libretro_GetCoreDirectory (SDL_Libretro *lr)
	Get the core directory.
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.
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.
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.
SDL_LibretroFitMode	SDL_Libretro_GetFitMode (const SDL_Libretro *lr)
	Gets how the frame is fit into the destination rectangle when rendered.
double	SDL_Libretro_GetFPS (const SDL_Libretro *lr)
	Gets the frame rate the core expects to run at.
const char *	SDL_Libretro_GetGameName (const SDL_Libretro *lr)
	Retrieve the human-readable name of the loaded game.
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.
int	SDL_Libretro_GetLanguage (const SDL_Libretro *lr)
	Get the language reported to cores through RETRO_ENVIRONMENT_GET_LANGUAGE.
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.
SDL_Libretro *	SDL_Libretro_GetMenuLibretro (const SDL_LibretroMenu *menu)
	Gets the libretro context the menu was created for.
SDL_LibretroMenuStyle	SDL_Libretro_GetMenuStyle (const SDL_LibretroMenu *menu)
	Gets the menu's active color theme.
void *	SDL_Libretro_GetMenuUserData (const SDL_LibretroMenu *menu)
	Gets the data attached with SDL_Libretro_SetMenuUserData().
const char *	SDL_Libretro_GetMessage (SDL_Libretro *lr)
	Gets the most relevant libretro message to display from the queue.
bool	SDL_Libretro_GetMessageByIndex (SDL_Libretro *lr, int index, const char **msg, int *progress, int *type)
	Retrieves all message details for the given message index.
unsigned	SDL_Libretro_GetMessageCount (SDL_Libretro *lr)
	Gets the number of messages currently in the queue.
int	SDL_Libretro_GetMessageProgress (SDL_Libretro *lr)
	Gets the progress of the message returned by SDL_Libretro_GetMessage().
int	SDL_Libretro_GetMessageType (SDL_Libretro *lr)
	Gets the type of the message returned by SDL_Libretro_GetMessage().
unsigned	SDL_Libretro_GetMousePort (const SDL_Libretro *lr)
	Get the controller port that the mouse drives.
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.
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.
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.
int	SDL_Libretro_GetRotation (const SDL_Libretro *lr)
	Gets the screen rotation requested by the core.
double	SDL_Libretro_GetSampleRate (const SDL_Libretro *lr)
	Get the audio sample rate the loaded core outputs at.
const char *	SDL_Libretro_GetSaveDirectory (SDL_Libretro *lr)
	Get the save directory.
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.
enum retro_savestate_context	SDL_Libretro_GetSavestateContext (const SDL_Libretro *lr)
	Get the savestate context reported to cores through RETRO_ENVIRONMENT_GET_SAVESTATE_CONTEXT.
SDL_ScaleMode	SDL_Libretro_GetScaleMode (const SDL_Libretro *lr)
	Gets the texture scale mode used when the libretro frame is scaled.
void	SDL_Libretro_GetSize (const SDL_Libretro *lr, int *w, int *h)
	Gets the width and height of the core's current video frame.
float	SDL_Libretro_GetSpeed (const SDL_Libretro *lr)
	Get how fast the game runs, as a multiple of its normal speed.
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.
const char *	SDL_Libretro_GetSystemDirectory (SDL_Libretro *lr)
	Get the system directory.
SDL_Texture *	SDL_Libretro_GetTexture (const SDL_Libretro *lr)
	Get the streaming texture that holds the core's most recent video frame.
const char *	SDL_Libretro_GetUsername (SDL_Libretro *lr)
	Get the username reported to cores.
const char *	SDL_Libretro_GetValidExtensions (const SDL_Libretro *lr)
	Gets the default set of valid extensions associated with the core, seperated by a "|".
int	SDL_Libretro_GetVersion (void)
	Get the version of SDL_libretro the implementation was compiled with.
float	SDL_Libretro_GetVolume (const SDL_Libretro *lr)
	Get the audio volume.
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_HandleMenuEvent (SDL_LibretroMenu *menu, const SDL_Event *event)
	Routes an event to the menu; call this for every event, before SDL_Libretro_HandleEvent().
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_InsertDisk (SDL_Libretro *lr)
	Closes the disk tray after a disk change.
bool	SDL_Libretro_IsCoreReady (const SDL_Libretro *lr)
	Indicates whether a core is loaded.
bool	SDL_Libretro_IsFastforwardOverrideActive (const SDL_Libretro *lr)
	Indicates whether the core is forcing fast-forward through RETRO_ENVIRONMENT_SET_FASTFORWARDING_OVERRIDE.
bool	SDL_Libretro_IsGameReady (const SDL_Libretro *lr)
	Indicates whether a game is loaded and running.
bool	SDL_Libretro_IsGameRequired (const SDL_Libretro *lr)
	Indicates whether the loaded core needs content to run.
bool	SDL_Libretro_IsMenuOpen (const SDL_LibretroMenu *menu)
	Checks whether the menu is currently shown.
bool	SDL_Libretro_LoadCore (SDL_Libretro *lr, const char *core)
	Loads a libretro core.
bool	SDL_Libretro_LoadGame (SDL_Libretro *lr, const char *gamePath)
	Loads a game at the given path.
bool	SDL_Libretro_LoadGame_IO (SDL_Libretro *lr, SDL_IOStream *src, const char *path, bool closeio)
	Loads a game from an SDL_IOStream.
bool	SDL_Libretro_LoadGameSpecial (SDL_Libretro *lr, const char *subsystem, const char **paths, unsigned numPaths)
	Loads multi-ROM subsystem content (e.g.
bool	SDL_Libretro_LoadGameSpecialById (SDL_Libretro *lr, unsigned subsystemId, const char **paths, unsigned numPaths)
	Load multi-ROM subsystem content by its numeric subsystem id.
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_MenuScreenshotClicked (SDL_LibretroMenu *menu, void *userdata)
	A ready-made menu callback that saves a PNG screenshot of the current frame, reporting the result in the menu.
bool	SDL_Libretro_OpenMenuPath (SDL_LibretroMenu *menu, const char *path)
	Opens the menu and navigates to a page by its slash-separated label path, e.g.
bool	SDL_Libretro_PhysFS_Init (SDL_Libretro *lr)
	Initialize PhysFS and route the libretro VFS through it.
bool	SDL_Libretro_PhysFS_LoadGame (SDL_Libretro *lr, const char *gamePath)
	Archive-aware replacement for SDL_Libretro_LoadGame().
void	SDL_Libretro_PhysFS_Quit (SDL_Libretro *lr)
	Tear down PhysFS, unmounting any active archive and restoring the plain SDL VFS on the given context.
bool	SDL_Libretro_Render (SDL_Libretro *lr, SDL_Renderer *renderer, const SDL_FRect *dstRect)
	Render the libretro context in the given renderer.
void	SDL_Libretro_RenderMenu (SDL_LibretroMenu *menu)
	Draws the menu laid out by SDL_Libretro_UpdateMenu() to the renderer.
bool	SDL_Libretro_Reset (SDL_Libretro *lr)
	Resets the loaded game, like pressing the console's reset button.
void	SDL_Libretro_ResetAllOptions (SDL_Libretro *lr)
	Reset every core option to its default value.
void	SDL_Libretro_ResetCheats (SDL_Libretro *lr)
	Clears all cheats that were set on the core.
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_SaveScreenshot (const SDL_Libretro *lr, const char *path)
	Saves a PNG screenshot of the current frame.
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.
void	SDL_Libretro_SetAnalogToDigital (SDL_Libretro *lr, unsigned port, SDL_LibretroAnalogToDigital stick)
	Selects which analog stick, if any, also registers D-Pad presses on the given controller port, alongside the physical D-Pad.
void	SDL_Libretro_SetAudioLatency (SDL_Libretro *lr, unsigned latencyMs)
	Set the desired minimum audio latency for the audio stream.
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_SetCoreAssetsDirectory (SDL_Libretro *lr, const char *path)
	Sets where cores look for their assets, reported through RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY.
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.
bool	SDL_Libretro_SetDiskIndex (SDL_Libretro *lr, unsigned index)
	Sets the disk image index to insert into the emulated drive.
bool	SDL_Libretro_SetFitMode (SDL_Libretro *lr, SDL_LibretroFitMode mode)
	Sets how the frame is fit into the destination rectangle when rendered.
void	SDL_Libretro_SetGamepadMapping (SDL_Libretro *lr, unsigned port, int retroButton, SDL_GamepadButton button)
	Maps an SDL gamepad button to a RETRO_DEVICE_ID_JOYPAD_* button on the given controller port.
bool	SDL_Libretro_SetInitialDisk (SDL_Libretro *lr, unsigned index, const char *path)
	Sets the disk image to insert once content is loaded.
void	SDL_Libretro_SetKeyboardMapping (SDL_Libretro *lr, int retroButton, SDL_Scancode scancode)
	Maps a keyboard key to a RETRO_DEVICE_ID_JOYPAD_* button for Player 1 (controller port 0).
void	SDL_Libretro_SetLanguage (SDL_Libretro *lr, int language)
	Override the language reported to cores through RETRO_ENVIRONMENT_GET_LANGUAGE.
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_SetMenuOpen (SDL_LibretroMenu *menu, bool open)
	Opens or closes the menu.
bool	SDL_Libretro_SetMenuStyle (SDL_LibretroMenu *menu, SDL_LibretroMenuStyle style)
	Applies a color theme to the menu.
void	SDL_Libretro_SetMenuUserData (SDL_LibretroMenu *menu, void *userData)
	Attaches generic application data to the menu.
void	SDL_Libretro_SetMessage (SDL_Libretro *lr, const char *msg, double duration)
	Add a message to be displayed within the libretro context.
void	SDL_Libretro_SetMousePort (SDL_Libretro *lr, unsigned port)
	Selects the one controller port that the mouse drives.
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_SetPortDevice (SDL_Libretro *lr, unsigned port, unsigned device)
	Assign a device type to a controller port.
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.
bool	SDL_Libretro_SetSaveDirectory (SDL_Libretro *lr, const char *path)
	Sets where content will be saved.
void	SDL_Libretro_SetSavestateContext (SDL_Libretro *lr, enum retro_savestate_context context)
	Sets the savestate context reported to cores through RETRO_ENVIRONMENT_GET_SAVESTATE_CONTEXT.
bool	SDL_Libretro_SetScaleMode (SDL_Libretro *lr, SDL_ScaleMode mode)
	Sets the texture scale mode used when the libretro frame is scaled.
void	SDL_Libretro_SetSpeed (SDL_Libretro *lr, float speed)
	Sets how fast the game runs, as a multiple of its normal speed.
void	SDL_Libretro_SetSRAMAutoSave (SDL_Libretro *lr, bool enabled)
	Load and save the core's battery-backed save RAM along with the game.
bool	SDL_Libretro_SetSystemDirectory (SDL_Libretro *lr, const char *path)
	Sets where cores look for system files (BIOS, firmware, etc).
bool	SDL_Libretro_SetUsername (SDL_Libretro *lr, const char *username)
	Sets the username reported to cores through RETRO_ENVIRONMENT_GET_USERNAME.
void	SDL_Libretro_SetVFS (SDL_Libretro *lr, void *vfs)
	Set the Virtual File System the core uses for file access.
void	SDL_Libretro_SetVirtualButton (SDL_Libretro *lr, unsigned port, int button, bool pressed)
	Press or release a joypad button from code, such as from an on-screen touch control.
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_ToggleMenu (SDL_LibretroMenu *menu)
	Opens the menu when it is closed, or closes it when it is open.
void	SDL_Libretro_UnloadCore (SDL_Libretro *lr)
	Unloads the actively loaded core.
void	SDL_Libretro_UnloadGame (SDL_Libretro *lr)
	Unloads the actively loaded game.
void	SDL_Libretro_Update (SDL_Libretro *lr)
	Runs the loaded game; call it once per frame of the application's loop.
void	SDL_Libretro_UpdateMenu (SDL_LibretroMenu *menu)
	Processes input and lays out the menu for this frame.
bool	SDL_Libretro_UpdateOptionVisibility (SDL_Libretro *lr)
	Ask the core to refresh which of its options should be displayed.

Detailed Description

SDL_libretro - SDL3 libretro frontend library.

Single-header library. To compile the implementation, define SDL_LIBRETRO_IMPLEMENTATION in exactly ONE translation unit before including this header:

#define SDL_LIBRETRO_IMPLEMENTATION
#include "SDL_libretro.h"

Every other translation unit includes "SDL_libretro.h" normally.

Copyright (c) 2026 Rob Loach

This software is provided "as-is", without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.

Definition in file SDL_libretro.h.

Macro Definition Documentation

SDL_LIBRETRO_MAX_USERS

#define SDL_LIBRETRO_MAX_USERS   4

The number of controller ports (gamepads) the frontend tracks.

This is the single source of truth for every per-port cap: gamepad, rumble and sensor arrays, port bound checks, and the value reported through RETRO_ENVIRONMENT_GET_INPUT_MAX_USERS.

Definition at line 571 of file SDL_libretro.h.