mirror/RetroArch
1
0
Fork 0
mirror of https://github.com/libretro/RetroArch synced 2025-04-07 13:23:32 +00:00
Code Issues Packages Projects Releases Wiki Activity
RetroArch/libretro-common/include/libretro.h
zoltanvb 198656eb20
Add support for multimedia keys (#16502) 
Extended RETROK_ values with 18 new items, commonly found on
"multimedia" keyboards.

Mapping added for SDL, X11, Wayland, dinput, winraw keymaps.

Keyboard tester function of Remote Retropad extended to cover new keys.

One fix in Android mapping for #12986
2024-05-11 17:06:54 -07:00

7816 lines
281 KiB
C++
Raw Blame History

/*!
* libretro.h is a simple API that allows for the creation of games and emulators.
*
* @file libretro.h
* @version 1
* @author libretro
* @copyright Copyright (C) 2010-2023 The RetroArch team
*
* @paragraph LICENSE
* The following license statement only applies to this libretro API header (libretro.h).
*
* Copyright (C) 2010-2023 The RetroArch team
*
* Permission is hereby granted, free of charge,
* to any person obtaining a copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
* and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
* WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
#ifndef LIBRETRO_H__
#define LIBRETRO_H__
#include <stdint.h>
#include <stddef.h>
#include <limits.h>
#ifdef __cplusplus
extern "C" {
#endif
#ifndef __cplusplus
#if defined(_MSC_VER) && _MSC_VER < 1800 && !defined(SN_TARGET_PS3)
/* Hack applied for MSVC when compiling in C89 mode
* as it isn't C99-compliant. */
#define bool unsigned char
#define true 1
#define false 0
#else
#include <stdbool.h>
#endif
#endif
#ifndef RETRO_CALLCONV
# if defined(__GNUC__) && defined(__i386__) && !defined(__x86_64__)
# define RETRO_CALLCONV __attribute__((cdecl))
# elif defined(_MSC_VER) && defined(_M_X86) && !defined(_M_X64)
# define RETRO_CALLCONV __cdecl
# else
# define RETRO_CALLCONV /* all other platforms only have one calling convention each */
# endif
#endif
#ifndef RETRO_API
# if defined(_WIN32) || defined(__CYGWIN__) || defined(__MINGW32__)
# ifdef RETRO_IMPORT_SYMBOLS
# ifdef __GNUC__
# define RETRO_API RETRO_CALLCONV __attribute__((__dllimport__))
# else
# define RETRO_API RETRO_CALLCONV __declspec(dllimport)
# endif
# else
# ifdef __GNUC__
# define RETRO_API RETRO_CALLCONV __attribute__((__dllexport__))
# else
# define RETRO_API RETRO_CALLCONV __declspec(dllexport)
# endif
# endif
# else
# if defined(__GNUC__) && __GNUC__ >= 4
# define RETRO_API RETRO_CALLCONV __attribute__((__visibility__("default")))
# else
# define RETRO_API RETRO_CALLCONV
# endif
# endif
#endif
/**
* The major version of the libretro API and ABI.
* Cores may support multiple versions,
* or they may reject cores with unsupported versions.
* It is only incremented for incompatible API/ABI changes;
* this generally implies a function was removed or changed,
* or that a \c struct had fields removed or changed.
* @note A design goal of libretro is to avoid having to increase this value at all costs.
* This is why there are APIs that are "extended" or "V2".
*/
#define RETRO_API_VERSION 1
/**
* @defgroup RETRO_DEVICE Input Devices
* @brief Libretro's fundamental device abstractions.
*
* Libretro's input system consists of abstractions over standard device types,
* such as a joypad (with or without analog), mouse, keyboard, light gun, or an abstract pointer.
* Instead of managing input devices themselves,
* cores need only to map their own concept of a controller to libretro's abstractions.
* This makes it possible for frontends to map the abstract types to a real input device
* without having to worry about the correct use of arbitrary (real) controller layouts.
* @{
*/
#define RETRO_DEVICE_TYPE_SHIFT 8
#define RETRO_DEVICE_MASK ((1 << RETRO_DEVICE_TYPE_SHIFT) - 1)
/**
* Defines an ID for a subclass of a known device type.
*
* To define a subclass ID, use this macro like so:
* @code{c}
* #define RETRO_DEVICE_SUPER_SCOPE RETRO_DEVICE_SUBCLASS(RETRO_DEVICE_LIGHTGUN, 1)
* #define RETRO_DEVICE_JUSTIFIER RETRO_DEVICE_SUBCLASS(RETRO_DEVICE_LIGHTGUN, 2)
* @endcode
*
* Correct use of this macro allows a frontend to select a suitable physical device
* to map to the emulated device.
*
* @note Cores must use the base ID when polling for input,
* and frontends must only accept the base ID for this purpose.
* Polling for input using subclass IDs is reserved for future definition.
*
* @param base One of the \ref RETRO_DEVICE "base device types".
* @param id A unique ID, with respect to \c base.
* Must be a non-negative integer.
* @return A unique subclass ID.
* @see retro_controller_description
* @see retro_set_controller_port_device
*/
#define RETRO_DEVICE_SUBCLASS(base, id) (((id + 1) << RETRO_DEVICE_TYPE_SHIFT) | base)
/**
* @defgroup RETRO_DEVICE Input Device Classes
* @{
*/
/**
* Indicates no input.
*
* When provided as the \c device argument to \c retro_input_state_t,
* all other arguments are ignored and zero is returned.
*
* @see retro_input_state_t
*/
#define RETRO_DEVICE_NONE 0
/**
* An abstraction around a game controller, known as a "RetroPad".
*
* The RetroPad is modelled after a SNES controller,
* but with additional L2/R2/L3/R3 buttons
* (similar to a PlayStation controller).
*
* When provided as the \c device argument to \c retro_input_state_t,
* the \c id argument denotes the button (including D-Pad directions) to query.
* The result of said query will be 1 if the button is down, 0 if not.
*
* There is one exception; if \c RETRO_DEVICE_ID_JOYPAD_MASK is queried
* (and the frontend supports this query),
* the result will be a bitmask of all pressed buttons.
*
* @see retro_input_state_t
* @see RETRO_DEVICE_ANALOG
* @see RETRO_DEVICE_ID_JOYPAD
* @see RETRO_DEVICE_ID_JOYPAD_MASK
* @see RETRO_ENVIRONMENT_GET_INPUT_BITMASKS
*/
#define RETRO_DEVICE_JOYPAD 1
/**
* An abstraction around a mouse, similar to the SNES Mouse but with more buttons.
*
* When provided as the \c device argument to \c retro_input_state_t,
* the \c id argument denotes the button or axis to query.
* For buttons, the result of said query
* will be 1 if the button is down or 0 if not.
* For mouse wheel axes, the result
* will be 1 if the wheel was rotated in that direction and 0 if not.
* For the mouse pointer axis, the result will be thee mouse's movement
* relative to the last poll.
* The core is responsible for tracking the mouse's position,
* and the frontend is responsible for preventing interference
* by the real hardware pointer (if applicable).
*
* @note This should only be used for cores that emulate mouse input,
* such as for home computers
* or consoles with mouse attachments.
* Cores that emulate light guns should use \c RETRO_DEVICE_LIGHTGUN,
* and cores that emulate touch screens should use \c RETRO_DEVICE_POINTER.
*
* @see RETRO_DEVICE_POINTER
* @see RETRO_DEVICE_LIGHTGUN
*/
#define RETRO_DEVICE_MOUSE 2
/**
* An abstraction around a keyboard.
*
* When provided as the \c device argument to \c retro_input_state_t,
* the \c id argument denotes the key to poll.
*
* @note This should only be used for cores that emulate keyboard input,
* such as for home computers
* or consoles with keyboard attachments.
* Cores that emulate gamepads should use \c RETRO_DEVICE_JOYPAD or \c RETRO_DEVICE_ANALOG,
* and leave keyboard compatibility to the frontend.
*
* @see RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK
* @see retro_key
*/
#define RETRO_DEVICE_KEYBOARD 3
/**
* An abstraction around a light gun, simular to the PlayStation's Guncon.
*
* When provided as the \c device argument to \c retro_input_state_t,
* the \c id argument denotes one of several possible inputs.
*
* The gun's coordinates are reported in screen space (similar to the pointer)
* in the range of [-0x8000, 0x7fff].
* Zero is the center of the game's screen
* and -0x8000 represents out-of-bounds.
* The trigger and various auxiliary buttons are also reported.
*
* @note A forced off-screen shot can be requested for auto-reloading
* function in some games.
*
* @see RETRO_DEVICE_POINTER
*/
#define RETRO_DEVICE_LIGHTGUN 4
/**
* An extension of the RetroPad that supports analog input.
*
* The analog RetroPad provides two virtual analog sticks (similar to DualShock controllers)
* and allows any button to be treated as analog (similar to Xbox shoulder triggers).
*
* When provided as the \c device argument to \c retro_input_state_t,
* the \c id argument denotes an analog axis or an analog button.
*
* Analog axes are reported in the range of [-0x8000, 0x7fff],
* with the X axis being positive towards the right
* and the Y axis being positive towards the bottom.
*
* Analog buttons are reported in the range of [0, 0x7fff],
* where 0 is unpressed and 0x7fff is fully pressed.
*
* @note Cores should only use this type if they need analog input.
* Otherwise, \c RETRO_DEVICE_JOYPAD should be used.
* @see RETRO_DEVICE_JOYPAD
*/
#define RETRO_DEVICE_ANALOG 5
/**
* Input Device: Pointer.
*
* Abstracts the concept of a pointing mechanism, e.g. touch.
* This allows libretro to query in absolute coordinates where on the
* screen a mouse (or something similar) is being placed.
* For a touch centric device, coordinates reported are the coordinates
* of the press.
*
* Coordinates in X and Y are reported as:
* [-0x7fff, 0x7fff]: -0x7fff corresponds to the far left/top of the screen,
* and 0x7fff corresponds to the far right/bottom of the screen.
* The "screen" is here defined as area that is passed to the frontend and
* later displayed on the monitor.
*
* The frontend is free to scale/resize this screen as it sees fit, however,
* (X, Y) = (-0x7fff, -0x7fff) will correspond to the top-left pixel of the
* game image, etc.
*
* To check if the pointer coordinates are valid (e.g. a touch display
* actually being touched), \c RETRO_DEVICE_ID_POINTER_PRESSED returns 1 or 0.
*
* If using a mouse on a desktop, \c RETRO_DEVICE_ID_POINTER_PRESSED will
* usually correspond to the left mouse button, but this is a frontend decision.
* \c RETRO_DEVICE_ID_POINTER_PRESSED will only return 1 if the pointer is
* inside the game screen.
*
* For multi-touch, the index variable can be used to successively query
* more presses.
* If index = 0 returns true for \c _PRESSED, coordinates can be extracted
* with \c _X, \c _Y for index = 0. One can then query \c _PRESSED, \c _X, \c _Y with
* index = 1, and so on.
* Eventually \c _PRESSED will return false for an index. No further presses
* are registered at this point.
*
* @see RETRO_DEVICE_MOUSE
* @see RETRO_DEVICE_ID_POINTER_X
* @see RETRO_DEVICE_ID_POINTER_Y
* @see RETRO_DEVICE_ID_POINTER_PRESSED
*/
#define RETRO_DEVICE_POINTER 6
/** @} */
/** @defgroup RETRO_DEVICE_ID_JOYPAD RetroPad Input
* @brief Digital buttons for the RetroPad.
*
* Button placement is comparable to that of a SNES controller,
* combined with the shoulder buttons of a PlayStation controller.
* These values can also be used for the \c id field of \c RETRO_DEVICE_INDEX_ANALOG_BUTTON
* to represent analog buttons (usually shoulder triggers).
* @{
*/
/** The equivalent of the SNES controller's south face button. */
#define RETRO_DEVICE_ID_JOYPAD_B 0
/** The equivalent of the SNES controller's west face button. */
#define RETRO_DEVICE_ID_JOYPAD_Y 1
/** The equivalent of the SNES controller's left-center button. */
#define RETRO_DEVICE_ID_JOYPAD_SELECT 2
/** The equivalent of the SNES controller's right-center button. */
#define RETRO_DEVICE_ID_JOYPAD_START 3
/** Up on the RetroPad's D-pad. */
#define RETRO_DEVICE_ID_JOYPAD_UP 4
/** Down on the RetroPad's D-pad. */
#define RETRO_DEVICE_ID_JOYPAD_DOWN 5
/** Left on the RetroPad's D-pad. */
#define RETRO_DEVICE_ID_JOYPAD_LEFT 6
/** Right on the RetroPad's D-pad. */
#define RETRO_DEVICE_ID_JOYPAD_RIGHT 7
/** The equivalent of the SNES controller's east face button. */
#define RETRO_DEVICE_ID_JOYPAD_A 8
/** The equivalent of the SNES controller's north face button. */
#define RETRO_DEVICE_ID_JOYPAD_X 9
/** The equivalent of the SNES controller's left shoulder button. */
#define RETRO_DEVICE_ID_JOYPAD_L 10
/** The equivalent of the SNES controller's right shoulder button. */
#define RETRO_DEVICE_ID_JOYPAD_R 11
/** The equivalent of the PlayStation's rear left shoulder button. */
#define RETRO_DEVICE_ID_JOYPAD_L2 12
/** The equivalent of the PlayStation's rear right shoulder button. */
#define RETRO_DEVICE_ID_JOYPAD_R2 13
/**
* The equivalent of the PlayStation's left analog stick button,
* although the actual button need not be in this position.
*/
#define RETRO_DEVICE_ID_JOYPAD_L3 14
/**
* The equivalent of the PlayStation's right analog stick button,
* although the actual button need not be in this position.
*/
#define RETRO_DEVICE_ID_JOYPAD_R3 15
/**
* Represents a bitmask that describes the state of all \c RETRO_DEVICE_ID_JOYPAD button constants,
* rather than the state of a single button.
*
* @see RETRO_ENVIRONMENT_GET_INPUT_BITMASKS
* @see RETRO_DEVICE_JOYPAD
*/
#define RETRO_DEVICE_ID_JOYPAD_MASK 256
/** @} */
/** @defgroup RETRO_DEVICE_ID_ANALOG Analog RetroPad Input
* @{
*/
/* Index / Id values for ANALOG device. */
#define RETRO_DEVICE_INDEX_ANALOG_LEFT 0
#define RETRO_DEVICE_INDEX_ANALOG_RIGHT 1
#define RETRO_DEVICE_INDEX_ANALOG_BUTTON 2
#define RETRO_DEVICE_ID_ANALOG_X 0
#define RETRO_DEVICE_ID_ANALOG_Y 1
/** @} */
/* Id values for MOUSE. */
#define RETRO_DEVICE_ID_MOUSE_X 0
#define RETRO_DEVICE_ID_MOUSE_Y 1
#define RETRO_DEVICE_ID_MOUSE_LEFT 2
#define RETRO_DEVICE_ID_MOUSE_RIGHT 3
#define RETRO_DEVICE_ID_MOUSE_WHEELUP 4
#define RETRO_DEVICE_ID_MOUSE_WHEELDOWN 5
#define RETRO_DEVICE_ID_MOUSE_MIDDLE 6
#define RETRO_DEVICE_ID_MOUSE_HORIZ_WHEELUP 7
#define RETRO_DEVICE_ID_MOUSE_HORIZ_WHEELDOWN 8
#define RETRO_DEVICE_ID_MOUSE_BUTTON_4 9
#define RETRO_DEVICE_ID_MOUSE_BUTTON_5 10
/* Id values for LIGHTGUN. */
#define RETRO_DEVICE_ID_LIGHTGUN_SCREEN_X 13 /*Absolute Position*/
#define RETRO_DEVICE_ID_LIGHTGUN_SCREEN_Y 14 /*Absolute*/
#define RETRO_DEVICE_ID_LIGHTGUN_IS_OFFSCREEN 15 /*Status Check*/
#define RETRO_DEVICE_ID_LIGHTGUN_TRIGGER 2
#define RETRO_DEVICE_ID_LIGHTGUN_RELOAD 16 /*Forced off-screen shot*/
#define RETRO_DEVICE_ID_LIGHTGUN_AUX_A 3
#define RETRO_DEVICE_ID_LIGHTGUN_AUX_B 4
#define RETRO_DEVICE_ID_LIGHTGUN_START 6
#define RETRO_DEVICE_ID_LIGHTGUN_SELECT 7
#define RETRO_DEVICE_ID_LIGHTGUN_AUX_C 8
#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_UP 9
#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_DOWN 10
#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_LEFT 11
#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_RIGHT 12
/* deprecated */
#define RETRO_DEVICE_ID_LIGHTGUN_X 0 /*Relative Position*/
#define RETRO_DEVICE_ID_LIGHTGUN_Y 1 /*Relative*/
#define RETRO_DEVICE_ID_LIGHTGUN_CURSOR 3 /*Use Aux:A*/
#define RETRO_DEVICE_ID_LIGHTGUN_TURBO 4 /*Use Aux:B*/
#define RETRO_DEVICE_ID_LIGHTGUN_PAUSE 5 /*Use Start*/
/* Id values for POINTER. */
#define RETRO_DEVICE_ID_POINTER_X 0
#define RETRO_DEVICE_ID_POINTER_Y 1
#define RETRO_DEVICE_ID_POINTER_PRESSED 2
#define RETRO_DEVICE_ID_POINTER_COUNT 3
/** @} */
/* Returned from retro_get_region(). */
#define RETRO_REGION_NTSC 0
#define RETRO_REGION_PAL 1
/**
* Identifiers for supported languages.
* @see RETRO_ENVIRONMENT_GET_LANGUAGE
*/
enum retro_language
{
RETRO_LANGUAGE_ENGLISH = 0,
RETRO_LANGUAGE_JAPANESE = 1,
RETRO_LANGUAGE_FRENCH = 2,
RETRO_LANGUAGE_SPANISH = 3,
RETRO_LANGUAGE_GERMAN = 4,
RETRO_LANGUAGE_ITALIAN = 5,
RETRO_LANGUAGE_DUTCH = 6,
RETRO_LANGUAGE_PORTUGUESE_BRAZIL = 7,
RETRO_LANGUAGE_PORTUGUESE_PORTUGAL = 8,
RETRO_LANGUAGE_RUSSIAN = 9,
RETRO_LANGUAGE_KOREAN = 10,
RETRO_LANGUAGE_CHINESE_TRADITIONAL = 11,
RETRO_LANGUAGE_CHINESE_SIMPLIFIED = 12,
RETRO_LANGUAGE_ESPERANTO = 13,
RETRO_LANGUAGE_POLISH = 14,
RETRO_LANGUAGE_VIETNAMESE = 15,
RETRO_LANGUAGE_ARABIC = 16,
RETRO_LANGUAGE_GREEK = 17,
RETRO_LANGUAGE_TURKISH = 18,
RETRO_LANGUAGE_SLOVAK = 19,
RETRO_LANGUAGE_PERSIAN = 20,
RETRO_LANGUAGE_HEBREW = 21,
RETRO_LANGUAGE_ASTURIAN = 22,
RETRO_LANGUAGE_FINNISH = 23,
RETRO_LANGUAGE_INDONESIAN = 24,
RETRO_LANGUAGE_SWEDISH = 25,
RETRO_LANGUAGE_UKRAINIAN = 26,
RETRO_LANGUAGE_CZECH = 27,
RETRO_LANGUAGE_CATALAN_VALENCIA = 28,
RETRO_LANGUAGE_CATALAN = 29,
RETRO_LANGUAGE_BRITISH_ENGLISH = 30,
RETRO_LANGUAGE_HUNGARIAN = 31,
RETRO_LANGUAGE_BELARUSIAN = 32,
RETRO_LANGUAGE_GALICIAN = 33,
RETRO_LANGUAGE_NORWEGIAN = 34,
RETRO_LANGUAGE_LAST,
/** Defined to ensure that <tt>sizeof(retro_language) == sizeof(int)</tt>. Do not use. */
RETRO_LANGUAGE_DUMMY = INT_MAX
};
/** @defgroup RETRO_MEMORY Memory Types
* @{
*/
/* Passed to retro_get_memory_data/size().
* If the memory type doesn't apply to the
* implementation NULL/0 can be returned.
*/
#define RETRO_MEMORY_MASK 0xff
/* Regular save RAM. This RAM is usually found on a game cartridge,
* backed up by a battery.
* If save game data is too complex for a single memory buffer,
* the SAVE_DIRECTORY (preferably) or SYSTEM_DIRECTORY environment
* callback can be used. */
#define RETRO_MEMORY_SAVE_RAM 0
/* Some games have a built-in clock to keep track of time.
* This memory is usually just a couple of bytes to keep track of time.
*/
#define RETRO_MEMORY_RTC 1
/* System ram lets a frontend peek into a game systems main RAM. */
#define RETRO_MEMORY_SYSTEM_RAM 2
/* Video ram lets a frontend peek into a game systems video RAM (VRAM). */
#define RETRO_MEMORY_VIDEO_RAM 3
/** @} */
/* Keysyms used for ID in input state callback when polling RETRO_KEYBOARD. */
enum retro_key
{
RETROK_UNKNOWN = 0,
RETROK_FIRST = 0,
RETROK_BACKSPACE = 8,
RETROK_TAB = 9,
RETROK_CLEAR = 12,
RETROK_RETURN = 13,
RETROK_PAUSE = 19,
RETROK_ESCAPE = 27,
RETROK_SPACE = 32,
RETROK_EXCLAIM = 33,
RETROK_QUOTEDBL = 34,
RETROK_HASH = 35,
RETROK_DOLLAR = 36,
RETROK_AMPERSAND = 38,
RETROK_QUOTE = 39,
RETROK_LEFTPAREN = 40,
RETROK_RIGHTPAREN = 41,
RETROK_ASTERISK = 42,
RETROK_PLUS = 43,
RETROK_COMMA = 44,
RETROK_MINUS = 45,
RETROK_PERIOD = 46,
RETROK_SLASH = 47,
RETROK_0 = 48,
RETROK_1 = 49,
RETROK_2 = 50,
RETROK_3 = 51,
RETROK_4 = 52,
RETROK_5 = 53,
RETROK_6 = 54,
RETROK_7 = 55,
RETROK_8 = 56,
RETROK_9 = 57,
RETROK_COLON = 58,
RETROK_SEMICOLON = 59,
RETROK_LESS = 60,
RETROK_EQUALS = 61,
RETROK_GREATER = 62,
RETROK_QUESTION = 63,
RETROK_AT = 64,
RETROK_LEFTBRACKET = 91,
RETROK_BACKSLASH = 92,
RETROK_RIGHTBRACKET = 93,
RETROK_CARET = 94,
RETROK_UNDERSCORE = 95,
RETROK_BACKQUOTE = 96,
RETROK_a = 97,
RETROK_b = 98,
RETROK_c = 99,
RETROK_d = 100,
RETROK_e = 101,
RETROK_f = 102,
RETROK_g = 103,
RETROK_h = 104,
RETROK_i = 105,
RETROK_j = 106,
RETROK_k = 107,
RETROK_l = 108,
RETROK_m = 109,
RETROK_n = 110,
RETROK_o = 111,
RETROK_p = 112,
RETROK_q = 113,
RETROK_r = 114,
RETROK_s = 115,
RETROK_t = 116,
RETROK_u = 117,
RETROK_v = 118,
RETROK_w = 119,
RETROK_x = 120,
RETROK_y = 121,
RETROK_z = 122,
RETROK_LEFTBRACE = 123,
RETROK_BAR = 124,
RETROK_RIGHTBRACE = 125,
RETROK_TILDE = 126,
RETROK_DELETE = 127,
RETROK_KP0 = 256,
RETROK_KP1 = 257,
RETROK_KP2 = 258,
RETROK_KP3 = 259,
RETROK_KP4 = 260,
RETROK_KP5 = 261,
RETROK_KP6 = 262,
RETROK_KP7 = 263,
RETROK_KP8 = 264,
RETROK_KP9 = 265,
RETROK_KP_PERIOD = 266,
RETROK_KP_DIVIDE = 267,
RETROK_KP_MULTIPLY = 268,
RETROK_KP_MINUS = 269,
RETROK_KP_PLUS = 270,
RETROK_KP_ENTER = 271,
RETROK_KP_EQUALS = 272,
RETROK_UP = 273,
RETROK_DOWN = 274,
RETROK_RIGHT = 275,
RETROK_LEFT = 276,
RETROK_INSERT = 277,
RETROK_HOME = 278,
RETROK_END = 279,
RETROK_PAGEUP = 280,
RETROK_PAGEDOWN = 281,
RETROK_F1 = 282,
RETROK_F2 = 283,
RETROK_F3 = 284,
RETROK_F4 = 285,
RETROK_F5 = 286,
RETROK_F6 = 287,
RETROK_F7 = 288,
RETROK_F8 = 289,
RETROK_F9 = 290,
RETROK_F10 = 291,
RETROK_F11 = 292,
RETROK_F12 = 293,
RETROK_F13 = 294,
RETROK_F14 = 295,
RETROK_F15 = 296,
RETROK_NUMLOCK = 300,
RETROK_CAPSLOCK = 301,
RETROK_SCROLLOCK = 302,
RETROK_RSHIFT = 303,
RETROK_LSHIFT = 304,
RETROK_RCTRL = 305,
RETROK_LCTRL = 306,
RETROK_RALT = 307,
RETROK_LALT = 308,
RETROK_RMETA = 309,
RETROK_LMETA = 310,
RETROK_LSUPER = 311,
RETROK_RSUPER = 312,
RETROK_MODE = 313,
RETROK_COMPOSE = 314,
RETROK_HELP = 315,
RETROK_PRINT = 316,
RETROK_SYSREQ = 317,
RETROK_BREAK = 318,
RETROK_MENU = 319,
RETROK_POWER = 320,
RETROK_EURO = 321,
RETROK_UNDO = 322,
RETROK_OEM_102 = 323,
RETROK_BROWSER_BACK = 324,
RETROK_BROWSER_FORWARD = 325,
RETROK_BROWSER_REFRESH = 326,
RETROK_BROWSER_STOP = 327,
RETROK_BROWSER_SEARCH = 328,
RETROK_BROWSER_FAVORITES = 329,
RETROK_BROWSER_HOME = 330,
RETROK_VOLUME_MUTE = 331,
RETROK_VOLUME_DOWN = 332,
RETROK_VOLUME_UP = 333,
RETROK_MEDIA_NEXT = 334,
RETROK_MEDIA_PREV = 335,
RETROK_MEDIA_STOP = 336,
RETROK_MEDIA_PLAY_PAUSE = 337,
RETROK_LAUNCH_MAIL = 338,
RETROK_LAUNCH_MEDIA = 339,
RETROK_LAUNCH_APP1 = 340,
RETROK_LAUNCH_APP2 = 341,
RETROK_LAST,
RETROK_DUMMY = INT_MAX /* Ensure sizeof(enum) == sizeof(int) */
};
enum retro_mod
{
RETROKMOD_NONE = 0x0000,
RETROKMOD_SHIFT = 0x01,
RETROKMOD_CTRL = 0x02,
RETROKMOD_ALT = 0x04,
RETROKMOD_META = 0x08,
RETROKMOD_NUMLOCK = 0x10,
RETROKMOD_CAPSLOCK = 0x20,
RETROKMOD_SCROLLOCK = 0x40,
RETROKMOD_DUMMY = INT_MAX /* Ensure sizeof(enum) == sizeof(int) */
};
/**
* @defgroup RETRO_ENVIRONMENT Environment Callbacks
* @{
*/
/**
* This bit indicates that the associated environment call is experimental,
* and may be changed or removed in the future.
* Frontends should mask out this bit before handling the environment call.
*/
#define RETRO_ENVIRONMENT_EXPERIMENTAL 0x10000
/** Frontend-internal environment callbacks should include this bit. */
#define RETRO_ENVIRONMENT_PRIVATE 0x20000
/* Environment commands. */
/**
* Requests the frontend to set the screen rotation.
*
* @param[in] data <tt>const unsigned*</tt>.
* Valid values are 0, 1, 2, and 3.
* These numbers respectively set the screen rotation to 0, 90, 180, and 270 degrees counter-clockwise.
* @returns \c true if the screen rotation was set successfully.
*/
#define RETRO_ENVIRONMENT_SET_ROTATION 1
/**
* Queries whether the core should use overscan or not.
*
* @param[out] data <tt>bool*</tt>.
* Set to \c true if the core should use overscan,
* \c false if it should be cropped away.
* @returns \c true if the environment call is available.
* Does \em not indicate whether overscan should be used.
* @deprecated As of 2019 this callback is considered deprecated in favor of
* using core options to manage overscan in a more nuanced, core-specific way.
*/
#define RETRO_ENVIRONMENT_GET_OVERSCAN 2
/**
* Queries whether the frontend supports frame duping,
* in the form of passing \c NULL to the video frame callback.
*
* @param[out] data <tt>bool*</tt>.
* Set to \c true if the frontend supports frame duping.
* @returns \c true if the environment call is available.
* @see retro_video_refresh_t
*/
#define RETRO_ENVIRONMENT_GET_CAN_DUPE 3
/*
* Environ 4, 5 are no longer supported (GET_VARIABLE / SET_VARIABLES),
* and reserved to avoid possible ABI clash.
*/
/**
* @brief Displays a user-facing message for a short time.
*
* Use this callback to convey important status messages,
* such as errors or the result of long-running operations.
* For trivial messages or logging, use \c RETRO_ENVIRONMENT_GET_LOG_INTERFACE or \c stderr.
*
* \code{.c}
* void set_message_example(void)
* {
* struct retro_message msg;
* msg.frames = 60 * 5; // 5 seconds
* msg.msg = "Hello world!";
*
* environ_cb(RETRO_ENVIRONMENT_SET_MESSAGE, &msg);
* }
* \endcode
*
* @deprecated Prefer using \c RETRO_ENVIRONMENT_SET_MESSAGE_EXT for new code,
* as it offers more features.
* Only use this environment call for compatibility with older cores or frontends.
*
* @param[in] data <tt>const struct retro_message*</tt>.
* Details about the message to show to the user.
* Behavior is undefined if <tt>NULL</tt>.
* @returns \c true if the environment call is available.
* @see retro_message
* @see RETRO_ENVIRONMENT_GET_LOG_INTERFACE
* @see RETRO_ENVIRONMENT_SET_MESSAGE_EXT
* @see RETRO_ENVIRONMENT_SET_MESSAGE
* @see RETRO_ENVIRONMENT_GET_MESSAGE_INTERFACE_VERSION
* @note The frontend must make its own copy of the message and the underlying string.
*/
#define RETRO_ENVIRONMENT_SET_MESSAGE 6
/**
* Requests the frontend to shutdown the core.
* Should only be used if the core can exit on its own,
* such as from a menu item in a game
* or an emulated power-off in an emulator.
*
* @param data Ignored.
* @returns \c true if the environment call is available.
*/
#define RETRO_ENVIRONMENT_SHUTDOWN 7
/**
* Gives a hint to the frontend of how demanding this core is on the system.
* For example, reporting a level of 2 means that
* this implementation should run decently on frontends
* of level 2 and above.
*
* It can be used by the frontend to potentially warn
* about too demanding implementations.
*
* The levels are "floating".
*
* This function can be called on a per-game basis,
* as a core may have different demands for different games or settings.
* If called, it should be called in <tt>retro_load_game()</tt>.
* @param[in] data <tt>const unsigned*</tt>.
*/
#define RETRO_ENVIRONMENT_SET_PERFORMANCE_LEVEL 8
/**
* Returns the path to the frontend's system directory,
* which can be used to store system-specific configuration
* such as BIOS files or cached data.
*
* @param[out] data <tt>const char**</tt>.
* Pointer to the \c char* in which the system directory will be saved.
* The string is managed by the frontend and must not be modified or freed by the core.
* May be \c NULL if no system directory is defined,
* in which case the core should find an alternative directory.
* @return \c true if the environment call is available,
* even if the value returned in \c data is <tt>NULL</tt>.
* @note Historically, some cores would use this folder for save data such as memory cards or SRAM.
* This is now discouraged in favor of \c RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY.
* @see RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY
*/
#define RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY 9
/**
* Sets the internal pixel format used by the frontend for rendering.
* The default pixel format is \c RETRO_PIXEL_FORMAT_0RGB1555 for compatibility reasons,
* although it's considered deprecated and shouldn't be used by new code.
*
* @param[in] data <tt>const enum retro_pixel_format *</tt>.
* Pointer to the pixel format to use.
* @returns \c true if the pixel format was set successfully,
* \c false if it's not supported or this callback is unavailable.
* @note This function should be called inside \c retro_load_game()
* or <tt>retro_get_system_av_info()</tt>.
* @see retro_pixel_format
*/
#define RETRO_ENVIRONMENT_SET_PIXEL_FORMAT 10
/**
* Sets an array of input descriptors for the frontend
* to present to the user for configuring the core's controls.
*
* This function can be called at any time,
* preferably early in the core's life cycle.
* Ideally, no later than \c retro_load_game().
*
* @param[in] data <tt>const struct retro_input_descriptor *</tt>.
* An array of input descriptors terminated by one whose
* \c retro_input_descriptor::description field is set to \c NULL.
* Behavior is undefined if \c NULL.
* @return \c true if the environment call is recognized.
* @see retro_input_descriptor
*/
#define RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS 11
/**
* Sets a callback function used to notify the core about keyboard events.
* This should only be used for cores that specifically need keyboard input,
* such as for home computer emulators or games with text entry.
*
* @param[in] data <tt>const struct retro_keyboard_callback *</tt>.
* Pointer to the callback function.
* Behavior is undefined if <tt>NULL</tt>.
* @return \c true if the environment call is recognized.
* @see retro_keyboard_callback
* @see retro_key
*/
#define RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK 12
/**
* Sets an interface that the frontend can use to insert and remove disks
* from the emulated console's disk drive.
* Can be used for optical disks, floppy disks, or any other game storage medium
* that can be swapped at runtime.
*
* This is intended for multi-disk games that expect the player
* to manually swap disks at certain points in the game.
*
* @deprecated Prefer using \c RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE
* over this environment call, as it supports additional features.
* Only use this callback to maintain compatibility
* with older cores or frontends.
*
* @param[in] data <tt>const struct retro_disk_control_callback *</tt>.
* Pointer to the callback functions to use.
* May be \c NULL, in which case the existing disk callback is deregistered.
* @return \c true if this environment call is available,
* even if \c data is \c NULL.
* @see retro_disk_control_callback
* @see RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE
*/
#define RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE 13
/**
* Requests that a frontend enable a particular hardware rendering API.
*
* If successful, the frontend will create a context (and other related resources)
* that the core can use for rendering.
* The framebuffer will be at least as large as
* the maximum dimensions provided in <tt>retro_get_system_av_info</tt>.
*
* @param[in, out] data <tt>struct retro_hw_render_callback *</tt>.
* Pointer to the hardware render callback struct.
* Used to define callbacks for the hardware-rendering life cycle,
* as well as to request a particular rendering API.
* @return \c true if the environment call is recognized
* and the requested rendering API is supported.
* \c false if \c data is \c NULL
* or the frontend can't provide the requested rendering API.
* @see retro_hw_render_callback
* @see retro_video_refresh_t
* @see RETRO_ENVIRONMENT_GET_PREFERRED_HW_RENDER
* @note Should be called in <tt>retro_load_game()</tt>.
* @note If HW rendering is used, pass only \c RETRO_HW_FRAME_BUFFER_VALID or
* \c NULL to <tt>retro_video_refresh_t</tt>.
*/
#define RETRO_ENVIRONMENT_SET_HW_RENDER 14
/**
* Retrieves a core option's value from the frontend.
* \c retro_variable::key should be set to an option key
* that was previously set in \c RETRO_ENVIRONMENT_SET_VARIABLES
* (or a similar environment call).
*
* @param[in,out] data <tt>struct retro_variable *</tt>.
* Pointer to a single \c retro_variable struct.
* See the documentation for \c retro_variable for details
* on which fields are set by the frontend or core.
* May be \c NULL.
* @returns \c true if the environment call is available,
* even if \c data is \c NULL or the key it specifies is not found.
* @note Passing \c NULL in to \c data can be useful to
* test for support of this environment call without looking up any variables.
* @see retro_variable
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
* @see RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE
*/
#define RETRO_ENVIRONMENT_GET_VARIABLE 15
/**
* Notifies the frontend of the core's available options.
*
* The core may check these options later using \c RETRO_ENVIRONMENT_GET_VARIABLE.
* The frontend may also present these options to the user
* in its own configuration UI.
*
* This should be called the first time as early as possible,
* ideally in \c retro_set_environment.
* The core may later call this function again
* to communicate updated options to the frontend,
* but the number of core options must not change.
*
* Here's an example that sets two options.
*
* @code
* void set_variables_example(void)
* {
* struct retro_variable options[] = {
* { "foo_speedhack", "Speed hack; false|true" }, // false by default
* { "foo_displayscale", "Display scale factor; 1|2|3|4" }, // 1 by default
* { NULL, NULL },
* };
*
* environ_cb(RETRO_ENVIRONMENT_SET_VARIABLES, &options);
* }
* @endcode
*
* The possible values will generally be displayed and stored as-is by the frontend.
*
* @deprecated Prefer using \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 for new code,
* as it offers more features such as categories and translation.
* Only use this environment call to maintain compatibility
* with older frontends or cores.
* @note Keep the available options (and their possible values) as low as possible;
* it should be feasible to cycle through them without a keyboard.
* @param[in] data <tt>const struct retro_variable *</tt>.
* Pointer to an array of \c retro_variable structs that define available core options,
* terminated by a <tt>{ NULL, NULL }</tt> element.
* The frontend must maintain its own copy of this array.
*
* @returns \c true if the environment call is available,
* even if \c data is <tt>NULL</tt>.
* @see retro_variable
* @see RETRO_ENVIRONMENT_GET_VARIABLE
* @see RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
*/
#define RETRO_ENVIRONMENT_SET_VARIABLES 16
/**
* Queries whether at least one core option was updated by the frontend
* since the last call to \ref RETRO_ENVIRONMENT_GET_VARIABLE.
* This typically means that the user opened the core options menu and made some changes.
*
* Cores usually call this each frame before the core's main emulation logic.
* Specific options can then be queried with \ref RETRO_ENVIRONMENT_GET_VARIABLE.
*
* @param[out] data <tt>bool *</tt>.
* Set to \c true if at least one core option was updated
* since the last call to \ref RETRO_ENVIRONMENT_GET_VARIABLE.
* Behavior is undefined if this pointer is \c NULL.
* @returns \c true if the environment call is available.
* @see RETRO_ENVIRONMENT_GET_VARIABLE
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
*/
#define RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE 17
/**
* Notifies the frontend that this core can run without loading any content,
* such as when emulating a console that has built-in software.
* When a core is loaded without content,
* \c retro_load_game receives an argument of <tt>NULL</tt>.
* This should be called within \c retro_set_environment() only.
*
* @param[in] data <tt>const bool *</tt>.
* Pointer to a single \c bool that indicates whether this frontend can run without content.
* Can point to a value of \c false but this isn't necessary,
* as contentless support is opt-in.
* The behavior is undefined if \c data is <tt>NULL</tt>.
* @returns \c true if the environment call is available.
* @see retro_load_game
*/
#define RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME 18
/**
* Retrieves the absolute path from which this core was loaded.
* Useful when loading assets from paths relative to the core,
* as is sometimes the case when using <tt>RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME</tt>.
*
* @param[out] data <tt>const char **</tt>.
* Pointer to a string in which the core's path will be saved.
* The string is managed by the frontend and must not be modified or freed by the core.
* May be \c NULL if the core is statically linked to the frontend
* or if the core's path otherwise cannot be determined.
* Behavior is undefined if \c data is <tt>NULL</tt>.
* @returns \c true if the environment call is available.
*/
#define RETRO_ENVIRONMENT_GET_LIBRETRO_PATH 19
/* Environment call 20 was an obsolete version of SET_AUDIO_CALLBACK.
* It was not used by any known core at the time, and was removed from the API.
* The number 20 is reserved to prevent ABI clashes.
*/
/**
* Sets a callback that notifies the core of how much time has passed
* since the last iteration of <tt>retro_run</tt>.
* If the frontend is not running the core in real time
* (e.g. it's frame-stepping or running in slow motion),
* then the reference value will be provided to the callback instead.
*
* @param[in] data <tt>const struct retro_frame_time_callback *</tt>.
* Pointer to a single \c retro_frame_time_callback struct.
* Behavior is undefined if \c data is <tt>NULL</tt>.
* @returns \c true if the environment call is available.
* @note Frontends may disable this environment call in certain situations.
* It will return \c false in those cases.
* @see retro_frame_time_callback
*/
#define RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK 21
/**
* Registers a set of functions that the frontend can use
* to tell the core it's ready for audio output.
*
* It is intended for games that feature asynchronous audio.
* It should not be used for emulators unless their audio is asynchronous.
*
*
* The callback only notifies about writability; the libretro core still
* has to call the normal audio callbacks
* to write audio. The audio callbacks must be called from within the
* notification callback.
* The amount of audio data to write is up to the core.
* Generally, the audio callback will be called continously in a loop.
*
* A frontend may disable this callback in certain situations.
* The core must be able to render audio with the "normal" interface.
*
* @param[in] data <tt>const struct retro_audio_callback *</tt>.
* Pointer to a set of functions that the frontend will call to notify the core
* when it's ready to receive audio data.
* May be \c NULL, in which case the frontend will return
* whether this environment callback is available.
* @return \c true if this environment call is available,
* even if \c data is \c NULL.
* @warning The provided callbacks can be invoked from any thread,
* so their implementations \em must be thread-safe.
* @note If a core uses this callback,
* it should also use <tt>RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK</tt>.
* @see retro_audio_callback
* @see retro_audio_sample_t
* @see retro_audio_sample_batch_t
* @see RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK
*/
#define RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK 22
/**
* Gets an interface that a core can use to access a controller's rumble motors.
*
* The interface supports two independently-controlled motors,
* one strong and one weak.
*
* Should be called from either \c retro_init() or \c retro_load_game(),
* but not from \c retro_set_environment().
*
* @param[out] data <tt>struct retro_rumble_interface *</tt>.
* Pointer to the interface struct.
* Behavior is undefined if \c NULL.
* @returns \c true if the environment call is available,
* even if the current device doesn't support vibration.
* @see retro_rumble_interface
* @defgroup GET_RUMBLE_INTERFACE Rumble Interface
*/
#define RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE 23
/**
* Returns the frontend's supported input device types.
*
* The supported device types are returned as a bitmask,
* with each value of \ref RETRO_DEVICE corresponding to a bit.
*
* Should only be called in \c retro_run().
*
* @code
* #define REQUIRED_DEVICES ((1 << RETRO_DEVICE_JOYPAD) | (1 << RETRO_DEVICE_ANALOG))
* void get_input_device_capabilities_example(void)
* {
* uint64_t capabilities;
* environ_cb(RETRO_ENVIRONMENT_GET_INPUT_DEVICE_CAPABILITIES, &capabilities);
* if ((capabilities & REQUIRED_DEVICES) == REQUIRED_DEVICES)
* printf("Joypad and analog device types are supported");
* }
* @endcode
*
* @param[out] data <tt>uint64_t *</tt>.
* Pointer to a bitmask of supported input device types.
* If the frontend supports a particular \c RETRO_DEVICE_* type,
* then the bit <tt>(1 << RETRO_DEVICE_*)</tt> will be set.
*
* Each bit represents a \c RETRO_DEVICE constant,
* e.g. bit 1 represents \c RETRO_DEVICE_JOYPAD,
* bit 2 represents \c RETRO_DEVICE_MOUSE, and so on.
*
* Bits that do not correspond to known device types will be set to zero
* and are reserved for future use.
*
* Behavior is undefined if \c NULL.
* @returns \c true if the environment call is available.
* @note If the frontend supports multiple input drivers,
* availability of this environment call (and the reported capabilities)
* may depend on the active driver.
* @see RETRO_DEVICE
*/
#define RETRO_ENVIRONMENT_GET_INPUT_DEVICE_CAPABILITIES 24
/**
* Returns an interface that the core can use to access and configure available sensors,
* such as an accelerometer or gyroscope.
*
* @param[out] data <tt>struct retro_sensor_interface *</tt>.
* Pointer to the sensor interface that the frontend will populate.
* Behavior is undefined if is \c NULL.
* @returns \c true if the environment call is available,
* even if the device doesn't have any supported sensors.
* @see retro_sensor_interface
* @see retro_sensor_action
* @see RETRO_SENSOR
* @addtogroup RETRO_SENSOR
*/
#define RETRO_ENVIRONMENT_GET_SENSOR_INTERFACE (25 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Gets an interface to the device's video camera.
*
* The frontend delivers new video frames via a user-defined callback
* that runs in the same thread as \c retro_run().
* Should be called in \c retro_load_game().
*
* @param[in,out] data <tt>struct retro_camera_callback *</tt>.
* Pointer to the camera driver interface.
* Some fields in the struct must be filled in by the core,
* others are provided by the frontend.
* Behavior is undefined if \c NULL.
* @returns \c true if this environment call is available,
* even if an actual camera isn't.
* @note This API only supports one video camera at a time.
* If the device provides multiple cameras (e.g. inner/outer cameras on a phone),
* the frontend will choose one to use.
* @see retro_camera_callback
* @see RETRO_ENVIRONMENT_SET_HW_RENDER
*/
#define RETRO_ENVIRONMENT_GET_CAMERA_INTERFACE (26 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Gets an interface that the core can use for cross-platform logging.
* Certain platforms don't have a console or <tt>stderr</tt>,
* or they have their own preferred logging methods.
* The frontend itself may also display log output.
*
* @attention This should not be used for information that the player must immediately see,
* such as major errors or warnings.
* In most cases, this is best for information that will help you (the developer)
* identify problems when debugging or providing support.
* Unless a core or frontend is intended for advanced users,
* the player might not check (or even know about) their logs.
*
* @param[out] data <tt>struct retro_log_callback *</tt>.
* Pointer to the callback where the function pointer will be saved.
* Behavior is undefined if \c data is <tt>NULL</tt>.
* @returns \c true if the environment call is available.
* @see retro_log_callback
* @note Cores can fall back to \c stderr if this interface is not available.
*/
#define RETRO_ENVIRONMENT_GET_LOG_INTERFACE 27
/**
* Returns an interface that the core can use for profiling code
* and to access performance-related information.
*
* This callback supports performance counters, a high-resolution timer,
* and listing available CPU features (mostly SIMD instructions).
*
* @param[out] data <tt>struct retro_perf_callback *</tt>.
* Pointer to the callback interface.
* Behavior is undefined if \c NULL.
* @returns \c true if the environment call is available.
* @see retro_perf_callback
*/
#define RETRO_ENVIRONMENT_GET_PERF_INTERFACE 28
/**
* Returns an interface that the core can use to retrieve the device's location,
* including its current latitude and longitude.
*
* @param[out] data <tt>struct retro_location_callback *</tt>.
* Pointer to the callback interface.
* Behavior is undefined if \c NULL.
* @return \c true if the environment call is available,
* even if there's no location information available.
* @see retro_location_callback
*/
#define RETRO_ENVIRONMENT_GET_LOCATION_INTERFACE 29
/**
* @deprecated An obsolete alias to \c RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY kept for compatibility.
* @see RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY
**/
#define RETRO_ENVIRONMENT_GET_CONTENT_DIRECTORY 30
/**
* Returns the frontend's "core assets" directory,
* which can be used to store assets that the core needs
* such as art assets or level data.
*
* @param[out] data <tt>const char **</tt>.
* Pointer to a string in which the core assets directory will be saved.
* This string is managed by the frontend and must not be modified or freed by the core.
* May be \c NULL if no core assets directory is defined,
* in which case the core should find an alternative directory.
* Behavior is undefined if \c data is <tt>NULL</tt>.
* @returns \c true if the environment call is available,
* even if the value returned in \c data is <tt>NULL</tt>.
*/
#define RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY 30
/**
* Returns the frontend's save data directory, if available.
* This directory should be used to store game-specific save data,
* including memory card images.
*
* Although libretro provides an interface for cores to expose SRAM to the frontend,
* not all cores can support it correctly.
* In this case, cores should use this environment callback
* to save their game data to disk manually.
*
* Cores that use this environment callback
* should flush their save data to disk periodically and when unloading.
*
* @param[out] data <tt>const char **</tt>.
* Pointer to the string in which the save data directory will be saved.
* This string is managed by the frontend and must not be modified or freed by the core.
* May return \c NULL if no save data directory is defined.
* Behavior is undefined if \c data is <tt>NULL</tt>.
* @returns \c true if the environment call is available,
* even if the value returned in \c data is <tt>NULL</tt>.
* @note Early libretro cores used \c RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY for save data.
* This is still supported for backwards compatibility,
* but new cores should use this environment call instead.
* \c RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY should be used for game-agnostic data
* such as BIOS files or core-specific configuration.
* @note The returned directory may or may not be the same
* as the one used for \c retro_get_memory_data.
*
* @see retro_get_memory_data
* @see RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY
*/
#define RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY 31
/**
* Sets new video and audio parameters for the core.
* This can only be called from within <tt>retro_run</tt>.
*
* This environment call may entail a full reinitialization of the frontend's audio/video drivers,
* hence it should \em only be used if the core needs to make drastic changes
* to audio/video parameters.
*
* This environment call should \em not be used when:
* <ul>
* <li>Changing the emulated system's internal resolution,
* within the limits defined by the existing values of \c max_width and \c max_height.
* Use \c RETRO_ENVIRONMENT_SET_GEOMETRY instead,
* and adjust \c retro_get_system_av_info to account fo
* supported scale factors and screen layouts
* when computing \c max_width and \c max_height.
* Only use this environment call if \c max_width or \c max_height needs to increase.
* <li>Adjusting the screen's aspect ratio,
* e.g. when changing the layout of the screen(s).
* Use \c RETRO_ENVIRONMENT_SET_GEOMETRY or \c RETRO_ENVIRONMENT_SET_ROTATION instead.
* </ul>
*
* The frontend will reinitialize its audio and video drivers within this callback;
* after that happens, audio and video callbacks will target the newly-initialized driver,
* even within the same \c retro_run call.
*
* This callback makes it possible to support configurable resolutions
* while avoiding the need to compute the "worst case" values of \c max_width and \c max_height.
*
* @param[in] data <tt>const struct retro_system_av_info *</tt>.
* Pointer to the new video and audio parameters that the frontend should adopt.
* @returns \c true if the environment call is available
* and the new av_info struct was accepted.
* \c false if the environment call is unavailable or \c data is <tt>NULL</tt>.
* @see retro_system_av_info
* @see RETRO_ENVIRONMENT_SET_GEOMETRY
*/
#define RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO 32
/**
* Provides an interface that a frontend can use
* to get function pointers from the core.
*
* This allows cores to define their own extensions to the libretro API,
* or to expose implementations of a frontend's libretro extensions.
*
* @param[in] data <tt>const struct retro_get_proc_address_interface *</tt>.
* Pointer to the interface that the frontend can use to get function pointers from the core.
* The frontend must maintain its own copy of this interface.
* @returns \c true if the environment call is available
* and the returned interface was accepted.
* @note The provided interface may be called at any time,
* even before this environment call returns.
* @note Extensions should be prefixed with the name of the frontend or core that defines them.
* For example, a frontend named "foo" that defines a debugging extension
* should expect the core to define functions prefixed with "foo_debug_".
* @warning If a core wants to use this environment call,
* it \em must do so from within \c retro_set_environment().
* @see retro_get_proc_address_interface
*/
#define RETRO_ENVIRONMENT_SET_PROC_ADDRESS_CALLBACK 33
/**
* Registers a core's ability to handle "subsystems",
* which are secondary platforms that augment a core's primary emulated hardware.
*
* A core doesn't need to emulate a secondary platform
* in order to use it as a subsystem;
* as long as it can load a secondary file for some practical use,
* then this environment call is most likely suitable.
*
* Possible use cases of a subsystem include:
*
* \li Installing software onto an emulated console's internal storage,
* such as the Nintendo DSi.
* \li Emulating accessories that are used to support another console's games,
* such as the Super Game Boy or the N64 Transfer Pak.
* \li Inserting a secondary ROM into a console
* that features multiple cartridge ports,
* such as the Nintendo DS's Slot-2.
* \li Loading a save data file created and used by another core.
*
* Cores should \em not use subsystems for:
*
* \li Emulators that support multiple "primary" platforms,
* such as a Game Boy/Game Boy Advance core
* or a Sega Genesis/Sega CD/32X core.
* Use \c retro_system_content_info_override, \c retro_system_info,
* and/or runtime detection instead.
* \li Selecting different memory card images.
* Use dynamically-populated core options instead.
* \li Different variants of a single console,
* such the Game Boy vs. the Game Boy Color.
* Use core options or runtime detection instead.
* \li Games that span multiple disks.
* Use \c RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE
* and m3u-formatted playlists instead.
* \li Console system files (BIOS, firmware, etc.).
* Use \c RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY
* and a common naming convention instead.
*
* When the frontend loads a game via a subsystem,
* it must call \c retro_load_game_special() instead of \c retro_load_game().
*
* @param[in] data <tt>const struct retro_subsystem_info *</tt>.
* Pointer to an array of subsystem descriptors,
* terminated by a zeroed-out \c retro_subsystem_info struct.
* The frontend should maintain its own copy
* of this array and the strings within it.
* Behavior is undefined if \c NULL.
* @returns \c true if this environment call is available.
* @note This environment call \em must be called from within \c retro_set_environment(),
* as frontends may need the registered information before loading a game.
* @see retro_subsystem_info
* @see retro_load_game_special
*/
#define RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO 34
/**
* Declares one or more types of controllers supported by this core.
* The frontend may then allow the player to select one of these controllers in its menu.
*
* Many consoles had controllers that came in different versions,
* were extensible with peripherals,
* or could be held in multiple ways;
* this environment call can be used to represent these differences
* and adjust the core's behavior to match.
*
* Possible use cases include:
*
* \li Supporting different classes of a single controller that supported their own sets of games.
* For example, the SNES had two different lightguns (the Super Scope and the Justifier)
* whose games were incompatible with each other.
* \li Representing a platform's alternative controllers.
* For example, several platforms had music/rhythm games that included controllers
* shaped like musical instruments.
* \li Representing variants of a standard controller with additional inputs.
* For example, numerous consoles in the 90's introduced 6-button controllers for fighting games,
* steering wheels for racing games,
* or analog sticks for 3D platformers.
* \li Representing add-ons for consoles or standard controllers.
* For example, the 3DS had a Circle Pad Pro attachment that added a second analog stick.
* \li Selecting different configurations for a single controller.
* For example, the Wii Remote could be held sideways like a traditional game pad
* or in one hand like a wand.
* \li Providing multiple ways to simulate the experience of using a particular controller.
* For example, the Game Boy Advance featured several games
* with motion or light sensors in their cartridges;
* a core could provide controller configurations
* that allow emulating the sensors with either analog axes
* or with their host device's sensors.
*
* Should be called in retro_load_game.
* The frontend must maintain its own copy of the provided array,
* including all strings and subobjects.
* A core may exclude certain controllers for known incompatible games.
*
* When the frontend changes the active device for a particular port,
* it must call \c retro_set_controller_port_device() with that port's index
* and one of the IDs defined in its retro_controller_info::types field.
*
* Input ports are generally associated with different players
* (and the frontend's UI may reflect this with "Player 1" labels),
* but this is not required.
* Some games use multiple controllers for a single player,
* or some cores may use port indexes to represent an emulated console's
* alternative input peripherals.
*
* @param[in] data <tt>const struct retro_controller_info *</tt>.
* Pointer to an array of controller types defined by this core,
* terminated by a zeroed-out \c retro_controller_info.
* Each element of this array represents a controller port on the emulated device.
* Behavior is undefined if \c NULL.
* @returns \c true if this environment call is available.
* @see retro_controller_info
* @see retro_set_controller_port_device
* @see RETRO_DEVICE_SUBCLASS
*/
#define RETRO_ENVIRONMENT_SET_CONTROLLER_INFO 35
/**
* Notifies the frontend of the address spaces used by the core's emulated hardware,
* and of the memory maps within these spaces.
* This can be used by the frontend to provide cheats, achievements, or debugging capabilities.
* Should only be used by emulators, as it makes little sense for game engines.
*
* @note Cores should also expose these address spaces
* through retro_get_memory_data and \c retro_get_memory_size if applicable;
* this environment call is not intended to replace those two functions,
* as the emulated hardware may feature memory regions outside of its own address space
* that are nevertheless useful for the frontend.
*
* @param[in] data <tt>const struct retro_memory_map *</tt>.
* Pointer to a single memory-map listing.
* The frontend must maintain its own copy of this object and its contents,
* including strings and nested objects.
* Behavior is undefined if \c NULL.
* @returns \c true if this environment call is available.
* @see retro_memory_map
* @see retro_get_memory_data
* @see retro_memory_descriptor
*/
#define RETRO_ENVIRONMENT_SET_MEMORY_MAPS (36 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Resizes the viewport without reinitializing the video driver.
*
* Similar to \c RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO,
* but any changes that would require video reinitialization will not be performed.
* Can only be called from within \c retro_run().
*
* This environment call allows a core to revise the size of the viewport at will,
* which can be useful for emulated platforms that support dynamic resolution changes
* or for cores that support multiple screen layouts.
*
* A frontend must guarantee that this environment call completes in
* constant time.
*
* @param[in] data <tt>const struct retro_game_geometry *</tt>.
* Pointer to the new video parameters that the frontend should adopt.
* \c retro_game_geometry::max_width and \c retro_game_geometry::max_height
* will be ignored.
* Behavior is undefined if \c data is <tt>NULL</tt>.
* @return \c true if the environment call is available.
* @see RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO
*/
#define RETRO_ENVIRONMENT_SET_GEOMETRY 37
/**
* Returns the name of the user, if possible.
* This callback is suitable for cores that offer personalization,
* such as online facilities or user profiles on the emulated system.
* @param[out] data <tt>const char **</tt>.
* Pointer to the user name string.
* May be \c NULL, in which case the core should use a default name.
* The returned pointer is owned by the frontend and must not be modified or freed by the core.
* Behavior is undefined if \c NULL.
* @returns \c true if the environment call is available,
* even if the frontend couldn't provide a name.
*/
#define RETRO_ENVIRONMENT_GET_USERNAME 38
/**
* Returns the frontend's configured language.
* It can be used to localize the core's UI,
* or to customize the emulated firmware if applicable.
*
* @param[out] data <tt>retro_language *</tt>.
* Pointer to the language identifier.
* Behavior is undefined if \c NULL.
* @returns \c true if the environment call is available.
* @note The returned language may not be the same as the operating system's language.
* Cores should fall back to the operating system's language (or to English)
* if the environment call is unavailable or the returned language is unsupported.
* @see retro_language
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL
*/
#define RETRO_ENVIRONMENT_GET_LANGUAGE 39
/**
* Returns a frontend-managed framebuffer
* that the core may render directly into
*
* This environment call is provided as an optimization
* for cores that use software rendering
* (i.e. that don't use \refitem RETRO_ENVIRONMENT_SET_HW_RENDER "a graphics hardware API");
* specifically, the intended use case is to allow a core
* to render directly into frontend-managed video memory,
* avoiding the bandwidth use that copying a whole framebuffer from core to video memory entails.
*
* Must be called every frame if used,
* as this may return a different framebuffer each frame
* (e.g. for swap chains).
* However, a core may render to a different buffer even if this call succeeds.
*
* @param[in,out] data <tt>struct retro_framebuffer *</tt>.
* Pointer to a frontend's frame buffer and accompanying data.
* Some fields are set by the core, others are set by the frontend.
* Only guaranteed to be valid for the duration of the current \c retro_run call,
* and must not be used afterwards.
* Behavior is undefined if \c NULL.
* @return \c true if the environment call was recognized
* and the framebuffer was successfully returned.
* @see retro_framebuffer
*/
#define RETRO_ENVIRONMENT_GET_CURRENT_SOFTWARE_FRAMEBUFFER (40 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Returns an interface for accessing the data of specific rendering APIs.
* Not all hardware rendering APIs support or need this.
*
* The details of these interfaces are specific to each rendering API.
*
* @note \c retro_hw_render_callback::context_reset must be called by the frontend
* before this environment call can be used.
* Additionally, the contents of the returned interface are invalidated
* after \c retro_hw_render_callback::context_destroyed has been called.
* @param[out] data <tt>const struct retro_hw_render_interface **</tt>.
* The render interface for the currently-enabled hardware rendering API, if any.
* The frontend will store a pointer to the interface at the address provided here.
* The returned interface is owned by the frontend and must not be modified or freed by the core.
* Behavior is undefined if \c NULL.
* @return \c true if this environment call is available,
* the active graphics API has a libretro rendering interface,
* and the frontend is able to return said interface.
* \c false otherwise.
* @see RETRO_ENVIRONMENT_SET_HW_RENDER
* @see retro_hw_render_interface
* @note Since not every libretro-supported hardware rendering API
* has a \c retro_hw_render_interface implementation,
* a result of \c false is not necessarily an error.
*/
#define RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE (41 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Explicitly notifies the frontend of whether this core supports achievements.
* The core must expose its emulated address space via
* \c retro_get_memory_data or \c RETRO_ENVIRONMENT_GET_MEMORY_MAPS.
* Must be called before the first call to <tt>retro_run</tt>.
*
* If \ref retro_get_memory_data returns a valid address
* but this environment call is not used,
* the frontend (at its discretion) may or may not opt in the core to its achievements support.
* whether this core is opted in to the frontend's achievement support
* is left to the frontend's discretion.
* @param[in] data <tt>const bool *</tt>.
* Pointer to a single \c bool that indicates whether this core supports achievements.
* Behavior is undefined if \c data is <tt>NULL</tt>.
* @returns \c true if the environment call is available.
* @see RETRO_ENVIRONMENT_SET_MEMORY_MAPS
* @see retro_get_memory_data
*/
#define RETRO_ENVIRONMENT_SET_SUPPORT_ACHIEVEMENTS (42 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Defines an interface that the frontend can use
* to ask the core for the parameters it needs for a hardware rendering context.
* The exact semantics depend on \ref RETRO_ENVIRONMENT_SET_HW_RENDER "the active rendering API".
* Will be used some time after \c RETRO_ENVIRONMENT_SET_HW_RENDER is called,
* but before \c retro_hw_render_callback::context_reset is called.
*
* @param[in] data <tt>const struct retro_hw_render_context_negotiation_interface *</tt>.
* Pointer to the context negotiation interface.
* Will be populated by the frontend.
* Behavior is undefined if \c NULL.
* @return \c true if this environment call is supported,
* even if the current graphics API doesn't use
* a context negotiation interface (in which case the argument is ignored).
* @see retro_hw_render_context_negotiation_interface
* @see RETRO_ENVIRONMENT_GET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_SUPPORT
* @see RETRO_ENVIRONMENT_SET_HW_RENDER
*/
#define RETRO_ENVIRONMENT_SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE (43 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Notifies the frontend of any quirks associated with serialization.
*
* Should be set in either \c retro_init or \c retro_load_game, but not both.
* @param[in, out] data <tt>uint64_t *</tt>.
* Pointer to the core's serialization quirks.
* The frontend will set the flags of the quirks it supports
* and clear the flags of those it doesn't.
* Behavior is undefined if \c NULL.
* @return \c true if this environment call is supported.
* @see retro_serialize
* @see retro_unserialize
* @see RETRO_SERIALIZATION_QUIRK
*/
#define RETRO_ENVIRONMENT_SET_SERIALIZATION_QUIRKS 44
/**
* The frontend will try to use a "shared" context when setting up a hardware context.
* Mostly applicable to OpenGL.
*
* In order for this to have any effect,
* the core must call \c RETRO_ENVIRONMENT_SET_HW_RENDER at some point
* if it hasn't already.
*
* @param data Ignored.
* @returns \c true if the environment call is available
* and the frontend supports shared hardware contexts.
*/
#define RETRO_ENVIRONMENT_SET_HW_SHARED_CONTEXT (44 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Returns an interface that the core can use to access the file system.
* Should be called as early as possible.
*
* @param[in,out] data <tt>struct retro_vfs_interface_info *</tt>.
* Information about the desired VFS interface,
* as well as the interface itself.
* Behavior is undefined if \c NULL.
* @return \c true if this environment call is available
* and the frontend can provide a VFS interface of the requested version or newer.
* @see retro_vfs_interface_info
* @see file_path
* @see retro_dirent
* @see file_stream
*/
#define RETRO_ENVIRONMENT_GET_VFS_INTERFACE (45 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Returns an interface that the core can use
* to set the state of any accessible device LEDs.
*
* @param[out] data <tt>struct retro_led_interface *</tt>.
* Pointer to the LED interface that the frontend will populate.
* May be \c NULL, in which case the frontend will only return
* whether this environment callback is available.
* @returns \c true if the environment call is available,
* even if \c data is \c NULL
* or no LEDs are accessible.
* @see retro_led_interface
*/
#define RETRO_ENVIRONMENT_GET_LED_INTERFACE (46 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Returns hints about certain steps that the core may skip for this frame.
*
* A frontend may not need a core to generate audio or video in certain situations;
* this environment call sets a bitmask that indicates
* which steps the core may skip for this frame.
*
* This can be used to increase performance for some frontend features.
*
* @note Emulation accuracy should not be compromised;
* for example, if a core emulates a platform that supports display capture
* (i.e. looking at its own VRAM), then it should perform its rendering as normal
* unless it can prove that the emulated game is not using display capture.
*
* @param[out] data <tt>retro_av_enable_flags *</tt>.
* Pointer to the bitmask of steps that the frontend will skip.
* Other bits are set to zero and are reserved for future use.
* If \c NULL, the frontend will only return whether this environment callback is available.
* @returns \c true if the environment call is available,
* regardless of the value output to \c data.
* If \c false, the core should assume that the frontend will not skip any steps.
* @see retro_av_enable_flags
*/
#define RETRO_ENVIRONMENT_GET_AUDIO_VIDEO_ENABLE (47 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Gets an interface that the core can use for raw MIDI I/O.
*
* @param[out] data <tt>struct retro_midi_interface **</tt>.
* Pointer to the MIDI interface.
* May be \c NULL.
* @return \c true if the environment call is available,
* even if \c data is \c NULL.
* @see retro_midi_interface
*/
#define RETRO_ENVIRONMENT_GET_MIDI_INTERFACE (48 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Asks the frontend if it's currently in fast-forward mode.
* @param[out] data <tt>bool *</tt>.
* Set to \c true if the frontend is currently fast-forwarding its main loop.
* Behavior is undefined if \c data is <tt>NULL</tt>.
* @returns \c true if this environment call is available,
* regardless of the value returned in \c data.
*
* @see RETRO_ENVIRONMENT_SET_FASTFORWARDING_OVERRIDE
*/
#define RETRO_ENVIRONMENT_GET_FASTFORWARDING (49 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Returns the refresh rate the frontend is targeting, in Hz.
* The intended use case is for the core to use the result to select an ideal refresh rate.
*
* @param[out] data <tt>float *</tt>.
* Pointer to the \c float in which the frontend will store its target refresh rate.
* Behavior is undefined if \c data is <tt>NULL</tt>.
* @return \c true if this environment call is available,
* regardless of the value returned in \c data.
*/
#define RETRO_ENVIRONMENT_GET_TARGET_REFRESH_RATE (50 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Returns whether the frontend can return the state of all buttons at once as a bitmask,
* rather than requiring a series of individual calls to \c retro_input_state_t.
*
* If this callback returns \c true,
* you can get the state of all buttons by passing \c RETRO_DEVICE_ID_JOYPAD_MASK
* as the \c id parameter to \c retro_input_state_t.
* Bit #N represents the RETRO_DEVICE_ID_JOYPAD constant of value N,
* e.g. <tt>(1 << RETRO_DEVICE_ID_JOYPAD_A)</tt> represents the A button.
*
* @param data Ignored.
* @returns \c true if the frontend can report the complete digital joypad state as a bitmask.
* @see retro_input_state_t
* @see RETRO_DEVICE_JOYPAD
* @see RETRO_DEVICE_ID_JOYPAD_MASK
*/
#define RETRO_ENVIRONMENT_GET_INPUT_BITMASKS (51 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Returns the version of the core options API supported by the frontend.
*
* Over the years, libretro has used several interfaces
* for allowing cores to define customizable options.
* \ref SET_CORE_OPTIONS_V2 "Version 2 of the interface"
* is currently preferred due to its extra features,
* but cores and frontends should strive to support
* versions \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS "1"
* and \ref RETRO_ENVIRONMENT_SET_VARIABLES "0" as well.
* This environment call provides the information that cores need for that purpose.
*
* If this environment call returns \c false,
* then the core should assume version 0 of the core options API.
*
* @param[out] data <tt>unsigned *</tt>.
* Pointer to the integer that will store the frontend's
* supported core options API version.
* Behavior is undefined if \c NULL.
* @returns \c true if the environment call is available,
* \c false otherwise.
* @see RETRO_ENVIRONMENT_SET_VARIABLES
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
*/
#define RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION 52
/**
* @copybrief RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
*
* @deprecated This environment call has been superseded
* by RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2,
* which supports categorizing options into groups.
* This environment call should only be used to maintain compatibility
* with older cores and frontends.
*
* This environment call is intended to replace \c RETRO_ENVIRONMENT_SET_VARIABLES,
* and should only be called if \c RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION
* returns an API version of at least 1.
*
* This should be called the first time as early as possible,
* ideally in \c retro_set_environment (but \c retro_load_game is acceptable).
* It may then be called again later to update
* the core's options and their associated values,
* as long as the number of options doesn't change
* from the number given in the first call.
*
* The core can retrieve option values at any time with \c RETRO_ENVIRONMENT_GET_VARIABLE.
* If a saved value for a core option doesn't match the option definition's values,
* the frontend may treat it as incorrect and revert to the default.
*
* Core options and their values are usually defined in a large static array,
* but they may be generated at runtime based on the loaded game or system state.
* Here are some use cases for that:
*
* @li Selecting a particular file from one of the
* \ref RETRO_ENVIRONMENT_GET_ASSET_DIRECTORY "frontend's"
* \ref RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY "content"
* \ref RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY "directories",
* such as a memory card image or figurine data file.
* @li Excluding options that are not relevant to the current game,
* for cores that define a large number of possible options.
* @li Choosing a default value at runtime for a specific game,
* such as a BIOS file whose region matches that of the loaded content.
*
* @note A guiding principle of libretro's API design is that
* all common interactions (gameplay, menu navigation, etc.)
* should be possible without a keyboard.
* This implies that cores should keep the number of options and values
* as low as possible.
*
* Example entry:
* @code
* {
* "foo_option",
* "Speed hack coprocessor X",
* "Provides increased performance at the expense of reduced accuracy",
* {
* { "false", NULL },
* { "true", NULL },
* { "unstable", "Turbo (Unstable)" },
* { NULL, NULL },
* },
* "false"
* }
* @endcode
*
* @param[in] data <tt>const struct retro_core_option_definition *</tt>.
* Pointer to one or more core option definitions,
* terminated by a \ref retro_core_option_definition whose values are all zero.
* May be \c NULL, in which case the frontend will remove all existing core options.
* The frontend must maintain its own copy of this object,
* including all strings and subobjects.
* @return \c true if this environment call is available.
*
* @see retro_core_option_definition
* @see RETRO_ENVIRONMENT_GET_VARIABLE
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL
*/
#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS 53
/**
* A variant of \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS
* that supports internationalization.
*
* @deprecated This environment call has been superseded
* by \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL,
* which supports categorizing options into groups
* (plus translating the groups themselves).
* Only use this environment call to maintain compatibility
* with older cores and frontends.
*
* This should be called instead of \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS
* if the core provides translations for its options.
* General use is largely the same,
* but see \ref retro_core_options_intl for some important details.
*
* @param[in] data <tt>const struct retro_core_options_intl *</tt>.
* Pointer to a core's option values and their translations.
* @see retro_core_options_intl
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS
*/
#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL 54
/**
* Notifies the frontend that it should show or hide the named core option.
*
* Some core options aren't relevant in all scenarios,
* such as a submenu for hardware rendering flags
* when the software renderer is configured.
* This environment call asks the frontend to stop (or start)
* showing the named core option to the player.
* This is only a hint, not a requirement;
* the frontend may ignore this environment call.
* By default, all core options are visible.
*
* @note This environment call must \em only affect a core option's visibility,
* not its functionality or availability.
* \ref RETRO_ENVIRONMENT_GET_VARIABLE "Getting an invisible core option"
* must behave normally.
*
* @param[in] data <tt>const struct retro_core_option_display *</tt>.
* Pointer to a descriptor for the option that the frontend should show or hide.
* May be \c NULL, in which case the frontend will only return
* whether this environment callback is available.
* @return \c true if this environment call is available,
* even if \c data is \c NULL
* or the specified option doesn't exist.
* @see retro_core_option_display
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_UPDATE_DISPLAY_CALLBACK
*/
#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY 55
/**
* Returns the frontend's preferred hardware rendering API.
* Cores should use this information to decide which API to use with \c RETRO_ENVIRONMENT_SET_HW_RENDER.
* @param[out] data <tt>retro_hw_context_type *</tt>.
* Pointer to the hardware context type.
* Behavior is undefined if \c data is <tt>NULL</tt>.
* This value will be set even if the environment call returns <tt>false</tt>,
* unless the frontend doesn't implement it.
* @returns \c true if the environment call is available
* and the frontend is able to use a hardware rendering API besides the one returned.
* If \c false is returned and the core cannot use the preferred rendering API,
* then it should exit or fall back to software rendering.
* @note The returned value does not indicate which API is currently in use.
* For example, the frontend may return \c RETRO_HW_CONTEXT_OPENGL
* while a Direct3D context from a previous session is active;
* this would signal that the frontend's current preference is for OpenGL,
* possibly because the user changed their frontend's video driver while a game is running.
* @see retro_hw_context_type
* @see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE
* @see RETRO_ENVIRONMENT_SET_HW_RENDER
*/
#define RETRO_ENVIRONMENT_GET_PREFERRED_HW_RENDER 56
/**
* Returns the minimum version of the disk control interface supported by the frontend.
*
* If this environment call returns \c false or \c data is 0 or greater,
* then cores may use disk control callbacks
* with \c RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE.
* If the reported version is 1 or greater,
* then cores should use \c RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE instead.
*
* @param[out] data <tt>unsigned *</tt>.
* Pointer to the unsigned integer that the frontend's supported disk control interface version will be stored in.
* Behavior is undefined if \c NULL.
* @return \c true if this environment call is available.
* @see RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE
*/
#define RETRO_ENVIRONMENT_GET_DISK_CONTROL_INTERFACE_VERSION 57
/**
* @copybrief RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE
*
* This is intended for multi-disk games that expect the player
* to manually swap disks at certain points in the game.
* This version of the disk control interface provides
* more information about disk images.
* Should be called in \c retro_init.
*
* @param[in] data <tt>const struct retro_disk_control_ext_callback *</tt>.
* Pointer to the callback functions to use.
* May be \c NULL, in which case the existing disk callback is deregistered.
* @return \c true if this environment call is available,
* even if \c data is \c NULL.
* @see retro_disk_control_ext_callback
*/
#define RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE 58
/**
* Returns the version of the message interface supported by the frontend.
*
* A version of 0 indicates that the frontend
* only supports the legacy \c RETRO_ENVIRONMENT_SET_MESSAGE interface.
* A version of 1 indicates that the frontend
* supports \c RETRO_ENVIRONMENT_SET_MESSAGE_EXT as well.
* If this environment call returns \c false,
* the core should behave as if it had returned 0.
*
* @param[out] data <tt>unsigned *</tt>.
* Pointer to the result returned by the frontend.
* Behavior is undefined if \c NULL.
* @return \c true if this environment call is available.
* @see RETRO_ENVIRONMENT_SET_MESSAGE_EXT
* @see RETRO_ENVIRONMENT_SET_MESSAGE
*/
#define RETRO_ENVIRONMENT_GET_MESSAGE_INTERFACE_VERSION 59
/**
* Displays a user-facing message for a short time.
*
* Use this callback to convey important status messages,
* such as errors or the result of long-running operations.
* For trivial messages or logging, use \c RETRO_ENVIRONMENT_GET_LOG_INTERFACE or \c stderr.
*
* This environment call supersedes \c RETRO_ENVIRONMENT_SET_MESSAGE,
* as it provides many more ways to customize
* how a message is presented to the player.
* However, a frontend that supports this environment call
* must still support \c RETRO_ENVIRONMENT_SET_MESSAGE.
*
* @param[in] data <tt>const struct retro_message_ext *</tt>.
* Pointer to the message to display to the player.
* Behavior is undefined if \c NULL.
* @returns \c true if this environment call is available.
* @see retro_message_ext
* @see RETRO_ENVIRONMENT_GET_MESSAGE_INTERFACE_VERSION
*/
#define RETRO_ENVIRONMENT_SET_MESSAGE_EXT 60
/**
* Returns the number of active input devices currently provided by the frontend.
*
* This may change between frames,
* but will remain constant for the duration of each frame.
*
* If this callback returns \c true,
* a core need not poll any input device
* with an index greater than or equal to the returned value.
*
* If callback returns \c false,
* the number of active input devices is unknown.
* In this case, all input devices should be considered active.
*
* @param[out] data <tt>unsigned *</tt>.
* Pointer to the result returned by the frontend.
* Behavior is undefined if \c NULL.
* @return \c true if this environment call is available.
*/
#define RETRO_ENVIRONMENT_GET_INPUT_MAX_USERS 61
/**
* Registers a callback that the frontend can use to notify the core
* of the audio output buffer's occupancy.
* Can be used by a core to attempt frame-skipping to avoid buffer under-runs
* (i.e. "crackling" sounds).
*
* @param[in] data <tt>const struct retro_audio_buffer_status_callback *</tt>.
* Pointer to the the buffer status callback,
* or \c NULL to unregister any existing callback.
* @return \c true if this environment call is available,
* even if \c data is \c NULL.
*
* @see retro_audio_buffer_status_callback
*/
#define RETRO_ENVIRONMENT_SET_AUDIO_BUFFER_STATUS_CALLBACK 62
/**
* Requests a minimum frontend audio latency in milliseconds.
*
* This is a hint; the frontend may assign a different audio latency
* to accommodate hardware limits,
* although it should try to honor requests up to 512ms.
*
* This callback has no effect if the requested latency
* is less than the frontend's current audio latency.
* If value is zero or \c data is \c NULL,
* the frontend should set its default audio latency.
*
* May be used by a core to increase audio latency and
* reduce the risk of buffer under-runs (crackling)
* when performing 'intensive' operations.
*
* A core using RETRO_ENVIRONMENT_SET_AUDIO_BUFFER_STATUS_CALLBACK
* to implement audio-buffer-based frame skipping can get good results
* by setting the audio latency to a high (typically 6x or 8x)
* integer multiple of the expected frame time.
*
* This can only be called from within \c retro_run().
*
* @warning This environment call may require the frontend to reinitialize its audio system.
* This environment call should be used sparingly.
* If the driver is reinitialized,
* \ref retro_audio_callback_t "all audio callbacks" will be updated
* to target the newly-initialized driver.
*
* @param[in] data <tt>const unsigned *</tt>.
* Minimum audio latency, in milliseconds.
* @return \c true if this environment call is available,
* even if \c data is \c NULL.
*
* @see RETRO_ENVIRONMENT_SET_AUDIO_BUFFER_STATUS_CALLBACK
*/
#define RETRO_ENVIRONMENT_SET_MINIMUM_AUDIO_LATENCY 63
/**
* Allows the core to tell the frontend when it should enable fast-forwarding,
* rather than relying solely on the frontend and user interaction.
*
* Possible use cases include:
*
* \li Temporarily disabling a core's fastforward support
* while investigating a related bug.
* \li Disabling fastforward during netplay sessions,
* or when using an emulated console's network features.
* \li Automatically speeding up the game when in a loading screen
* that cannot be shortened with high-level emulation.
*
* @param[in] data <tt>const struct retro_fastforwarding_override *</tt>.
* Pointer to the parameters that decide when and how
* the frontend is allowed to enable fast-forward mode.
* May be \c NULL, in which case the frontend will return \c true
* without updating the fastforward state,
* which can be used to detect support for this environment call.
* @return \c true if this environment call is available,
* even if \c data is \c NULL.
*
* @see retro_fastforwarding_override
* @see RETRO_ENVIRONMENT_GET_FASTFORWARDING
*/
#define RETRO_ENVIRONMENT_SET_FASTFORWARDING_OVERRIDE 64
#define RETRO_ENVIRONMENT_SET_CONTENT_INFO_OVERRIDE 65
/* const struct retro_system_content_info_override * --
* Allows an implementation to override 'global' content
* info parameters reported by retro_get_system_info().
* Overrides also affect subsystem content info parameters
* set via RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO.
* This function must be called inside retro_set_environment().
* If callback returns false, content info overrides
* are unsupported by the frontend, and will be ignored.
* If callback returns true, extended game info may be
* retrieved by calling RETRO_ENVIRONMENT_GET_GAME_INFO_EXT
* in retro_load_game() or retro_load_game_special().
*
* 'data' points to an array of retro_system_content_info_override
* structs terminated by a { NULL, false, false } element.
* If 'data' is NULL, no changes will be made to the frontend;
* a core may therefore pass NULL in order to test whether
* the RETRO_ENVIRONMENT_SET_CONTENT_INFO_OVERRIDE and
* RETRO_ENVIRONMENT_GET_GAME_INFO_EXT callbacks are supported
* by the frontend.
*
* For struct member descriptions, see the definition of
* struct retro_system_content_info_override.
*
* Example:
*
* - struct retro_system_info:
* {
* "My Core", // library_name
* "v1.0", // library_version
* "m3u|md|cue|iso|chd|sms|gg|sg", // valid_extensions
* true, // need_fullpath
* false // block_extract
* }
*
* - Array of struct retro_system_content_info_override:
* {
* {
* "md|sms|gg", // extensions
* false, // need_fullpath
* true // persistent_data
* },
* {
* "sg", // extensions
* false, // need_fullpath
* false // persistent_data
* },
* { NULL, false, false }
* }
*
* Result:
* - Files of type m3u, cue, iso, chd will not be
* loaded by the frontend. Frontend will pass a
* valid path to the core, and core will handle
* loading internally
* - Files of type md, sms, gg will be loaded by
* the frontend. A valid memory buffer will be
* passed to the core. This memory buffer will
* remain valid until retro_deinit() returns
* - Files of type sg will be loaded by the frontend.
* A valid memory buffer will be passed to the core.
* This memory buffer will remain valid until
* retro_load_game() (or retro_load_game_special())
* returns
*
* NOTE: If an extension is listed multiple times in
* an array of retro_system_content_info_override
* structs, only the first instance will be registered
*/
#define RETRO_ENVIRONMENT_GET_GAME_INFO_EXT 66
/* const struct retro_game_info_ext ** --
* Allows an implementation to fetch extended game
* information, providing additional content path
* and memory buffer status details.
* This function may only be called inside
* retro_load_game() or retro_load_game_special().
* If callback returns false, extended game information
* is unsupported by the frontend. In this case, only
* regular retro_game_info will be available.
* RETRO_ENVIRONMENT_GET_GAME_INFO_EXT is guaranteed
* to return true if RETRO_ENVIRONMENT_SET_CONTENT_INFO_OVERRIDE
* returns true.
*
* 'data' points to an array of retro_game_info_ext structs.
*
* For struct member descriptions, see the definition of
* struct retro_game_info_ext.
*
* - If function is called inside retro_load_game(),
* the retro_game_info_ext array is guaranteed to
* have a size of 1 - i.e. the returned pointer may
* be used to access directly the members of the
* first retro_game_info_ext struct, for example:
*
* struct retro_game_info_ext *game_info_ext;
* if (environ_cb(RETRO_ENVIRONMENT_GET_GAME_INFO_EXT, &game_info_ext))
* printf("Content Directory: %s\n", game_info_ext->dir);
*
* - If the function is called inside retro_load_game_special(),
* the retro_game_info_ext array is guaranteed to have a
* size equal to the num_info argument passed to
* retro_load_game_special()
*/
/**
* Defines a set of core options that can be shown and configured by the frontend,
* so that the player may customize their gameplay experience to their liking.
*
* @note This environment call is intended to replace
* \c RETRO_ENVIRONMENT_SET_VARIABLES and \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS,
* and should only be called if \c RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION
* returns an API version of at least 2.
*
* This should be called the first time as early as possible,
* ideally in \c retro_set_environment (but \c retro_load_game is acceptable).
* It may then be called again later to update
* the core's options and their associated values,
* as long as the number of options doesn't change
* from the number given in the first call.
*
* The core can retrieve option values at any time with \c RETRO_ENVIRONMENT_GET_VARIABLE.
* If a saved value for a core option doesn't match the option definition's values,
* the frontend may treat it as incorrect and revert to the default.
*
* Core options and their values are usually defined in a large static array,
* but they may be generated at runtime based on the loaded game or system state.
* Here are some use cases for that:
*
* @li Selecting a particular file from one of the
* \ref RETRO_ENVIRONMENT_GET_ASSET_DIRECTORY "frontend's"
* \ref RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY "content"
* \ref RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY "directories",
* such as a memory card image or figurine data file.
* @li Excluding options that are not relevant to the current game,
* for cores that define a large number of possible options.
* @li Choosing a default value at runtime for a specific game,
* such as a BIOS file whose region matches that of the loaded content.
*
* @note A guiding principle of libretro's API design is that
* all common interactions (gameplay, menu navigation, etc.)
* should be possible without a keyboard.
* This implies that cores should keep the number of options and values
* as low as possible.
*
* @param[in] data <tt>const struct retro_core_options_v2 *</tt>.
* Pointer to a core's options and their associated categories.
* May be \c NULL, in which case the frontend will remove all existing core options.
* The frontend must maintain its own copy of this object,
* including all strings and subobjects.
* @return \c true if this environment call is available
* and the frontend supports categories.
* Note that this environment call is guaranteed to successfully register
* the provided core options,
* so the return value does not indicate success or failure.
*
* @see retro_core_options_v2
* @see retro_core_option_v2_category
* @see retro_core_option_v2_definition
* @see RETRO_ENVIRONMENT_GET_VARIABLE
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL
*/
#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 67
/**
* A variant of \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
* that supports internationalization.
*
* This should be called instead of \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
* if the core provides translations for its options.
* General use is largely the same,
* but see \ref retro_core_options_v2_intl for some important details.
*
* @param[in] data <tt>const struct retro_core_options_v2_intl *</tt>.
* Pointer to a core's option values and categories,
* plus a translation for each option and category.
* @see retro_core_options_v2_intl
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
*/
#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL 68
/**
* Registers a callback that the frontend can use
* to notify the core that at least one core option
* should be made hidden or visible.
* Allows a frontend to signal that a core must update
* the visibility of any dynamically hidden core options,
* and enables the frontend to detect visibility changes.
* Used by the frontend to update the menu display status
* of core options without requiring a call of retro_run().
* Must be called in retro_set_environment().
*
* @param[in] data <tt>const struct retro_core_options_update_display_callback *</tt>.
* The callback that the frontend should use.
* May be \c NULL, in which case the frontend will unset any existing callback.
* Can be used to query visibility support.
* @return \c true if this environment call is available,
* even if \c data is \c NULL.
* @see retro_core_options_update_display_callback
*/
#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_UPDATE_DISPLAY_CALLBACK 69
/**
* Forcibly sets a core option's value.
*
* After changing a core option value with this callback,
* it will be reflected in the frontend
* and \ref RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE will return \c true.
* \ref retro_variable::key must match
* a \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 "previously-set core option",
* and \ref retro_variable::value must match one of its defined values.
*
* Possible use cases include:
*
* @li Allowing the player to set certain core options
* without entering the frontend's option menu,
* using an in-core hotkey.
* @li Adjusting invalid combinations of settings.
* @li Migrating settings from older releases of a core.
*
* @param[in] data <tt>const struct retro_variable *</tt>.
* Pointer to a single option that the core is changing.
* May be \c NULL, in which case the frontend will return \c true
* to indicate that this environment call is available.
* @return \c true if this environment call is available
* and the option named by \c key was successfully
* set to the given \c value.
* \c false if the \c key or \c value fields are \c NULL, empty,
* or don't match a previously set option.
*
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
* @see RETRO_ENVIRONMENT_GET_VARIABLE
* @see RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE
*/
#define RETRO_ENVIRONMENT_SET_VARIABLE 70
#define RETRO_ENVIRONMENT_GET_THROTTLE_STATE (71 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/* struct retro_throttle_state * --
* Allows an implementation to get details on the actual rate
* the frontend is attempting to call retro_run().
*/
/**
* Returns information about how the frontend will use savestates.
*
* @param[out] data <tt>retro_savestate_context *</tt>.
* Pointer to the current savestate context.
* May be \c NULL, in which case the environment call
* will return \c true to indicate its availability.
* @returns \c true if the environment call is available,
* even if \c data is \c NULL.
* @see retro_savestate_context
*/
#define RETRO_ENVIRONMENT_GET_SAVESTATE_CONTEXT (72 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Before calling \c SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE, will query which interface is supported.
*
* Frontend looks at \c retro_hw_render_interface_type and returns the maximum supported
* context negotiation interface version. If the \c retro_hw_render_interface_type is not
* supported or recognized by the frontend, a version of 0 must be returned in
* \c retro_hw_render_interface's \c interface_version and \c true is returned by frontend.
*
* If this environment call returns true with a \c interface_version greater than 0,
* a core can always use a negotiation interface version larger than what the frontend returns,
* but only earlier versions of the interface will be used by the frontend.
*
* A frontend must not reject a negotiation interface version that is larger than what the
* frontend supports. Instead, the frontend will use the older entry points that it recognizes.
* If this is incompatible with a particular core's requirements, it can error out early.
*
* @note Regarding backwards compatibility, this environment call was introduced after Vulkan v1
* context negotiation. If this environment call is not supported by frontend, i.e. the environment
* call returns \c false , only Vulkan v1 context negotiation is supported (if Vulkan HW rendering
* is supported at all). If a core uses Vulkan negotiation interface with version > 1, negotiation
* may fail unexpectedly. All future updates to the context negotiation interface implies that
* frontend must support this environment call to query support.
*
* @param[out] data <tt>struct retro_hw_render_context_negotiation_interface *</tt>.
* @return \c true if the environment call is available.
* @see SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE
* @see retro_hw_render_interface_type
* @see retro_hw_render_context_negotiation_interface
*/
#define RETRO_ENVIRONMENT_GET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_SUPPORT (73 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Asks the frontend whether JIT compilation can be used.
* Primarily used by iOS and tvOS.
* @param[out] data <tt>bool *</tt>.
* Set to \c true if the frontend has verified that JIT compilation is possible.
* @return \c true if the environment call is available.
*/
#define RETRO_ENVIRONMENT_GET_JIT_CAPABLE 74
/**
* Returns an interface that the core can use to receive microphone input.
*
* @param[out] data <tt>retro_microphone_interface *</tt>.
* Pointer to the microphone interface.
* @return \true if microphone support is available,
* even if no microphones are plugged in.
* \c false if microphone support is disabled unavailable,
* or if \c data is \c NULL.
* @see retro_microphone_interface
*/
#define RETRO_ENVIRONMENT_GET_MICROPHONE_INTERFACE (75 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/* Environment 76 was an obsolete version of RETRO_ENVIRONMENT_SET_NETPACKET_INTERFACE.
* It was not used by any known core at the time, and was removed from the API. */
/**
* Returns the device's current power state as reported by the frontend.
*
* This is useful for emulating the battery level in handheld consoles,
* or for reducing power consumption when on battery power.
*
* @note This environment call describes the power state for the entire device,
* not for individual peripherals like controllers.
*
* @param[out] data <struct retro_device_power *>.
* Indicates whether the frontend can provide this information, even if the parameter
* is \c NULL. If the frontend does not support this functionality, then the provided
* argument will remain unchanged.
* @return \c true if the environment call is available.
* @see retro_device_power
*/
#define RETRO_ENVIRONMENT_GET_DEVICE_POWER (77 | RETRO_ENVIRONMENT_EXPERIMENTAL)
#define RETRO_ENVIRONMENT_SET_NETPACKET_INTERFACE 78
/* const struct retro_netpacket_callback * --
* When set, a core gains control over network packets sent and
* received during a multiplayer session. This can be used to
* emulate multiplayer games that were originally played on two
* or more separate consoles or computers connected together.
*
* The frontend will take care of connecting players together,
* and the core only needs to send the actual data as needed for
* the emulation, while handshake and connection management happen
* in the background.
*
* When two or more players are connected and this interface has
* been set, time manipulation features (such as pausing, slow motion,
* fast forward, rewinding, save state loading, etc.) are disabled to
* avoid interrupting communication.
*
* Should be set in either retro_init or retro_load_game, but not both.
*
* When not set, a frontend may use state serialization-based
* multiplayer, where a deterministic core supporting multiple
* input devices does not need to take any action on its own.
*/
/**
* Returns the device's current power state as reported by the frontend.
* This is useful for emulating the battery level in handheld consoles,
* or for reducing power consumption when on battery power.
*
* The return value indicates whether the frontend can provide this information,
* even if the parameter is \c NULL.
*
* If the frontend does not support this functionality,
* then the provided argument will remain unchanged.
* @param[out] data <tt>retro_device_power *</tt>.
* Pointer to the information that the frontend returns about its power state.
* May be \c NULL.
* @return \c true if the environment call is available,
* even if \c data is \c NULL.
* @see retro_device_power
* @note This environment call describes the power state for the entire device,
* not for individual peripherals like controllers.
*/
#define RETRO_ENVIRONMENT_GET_DEVICE_POWER (77 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/**
* Returns the "playlist" directory of the frontend.
*
* This directory can be used to store core generated playlists, in case
* this internal functionality is available (e.g. internal core game detection
* engine).
*
* @param[out] data <tt>const char **</tt>.
* May be \c NULL. If so, no such directory is defined, and it's up to the
* implementation to find a suitable directory.
* @return \c true if the environment call is available.
*/
#define RETRO_ENVIRONMENT_GET_PLAYLIST_DIRECTORY 79
/**@}*/
/**
* @defgroup GET_VFS_INTERFACE File System Interface
* @brief File system functionality.
*
* @section File Paths
* File paths passed to all libretro filesystem APIs shall be well formed UNIX-style,
* using "/" (unquoted forward slash) as the directory separator
* regardless of the platform's native separator.
*
* Paths shall also include at least one forward slash
* (e.g. use "./game.bin" instead of "game.bin").
*
* Other than the directory separator, cores shall not make assumptions about path format.
* The following paths are all valid:
* @li \c C:/path/game.bin
* @li \c http://example.com/game.bin
* @li \c #game/game.bin
* @li \c ./game.bin
*
* Cores may replace the basename or remove path components from the end, and/or add new components;
* however, cores shall not append "./", "../" or multiple consecutive forward slashes ("//") to paths they request from the front end.
*
* The frontend is encouraged to do the best it can when given an ill-formed path,
* but it is allowed to give up.
*
* Frontends are encouraged, but not required, to support native file system paths
* (including replacing the directory separator, if applicable).
*
* Cores are allowed to try using them, but must remain functional if the frontend rejects such requests.
*
* Cores are encouraged to use the libretro-common filestream functions for file I/O,
* as they seamlessly integrate with VFS,
* deal with directory separator replacement as appropriate
* and provide platform-specific fallbacks
* in cases where front ends do not provide their own VFS interface.
*
* @see RETRO_ENVIRONMENT_GET_VFS_INTERFACE
* @see retro_vfs_interface_info
* @see file_path
* @see retro_dirent
* @see file_stream
*
* @{
*/
/**
* Opaque file handle.
* @since VFS API v1
*/
struct retro_vfs_file_handle;
/**
* Opaque directory handle.
* @since VFS API v3
*/
struct retro_vfs_dir_handle;
/** @defgroup RETRO_VFS_FILE_ACCESS File Access Flags
* File access flags.
* @since VFS API v1
* @{
*/
/** Opens a file for read-only access. */
#define RETRO_VFS_FILE_ACCESS_READ (1 << 0)
/**
* Opens a file for write-only access.
* Any existing file at this path will be discarded and overwritten
* unless \c RETRO_VFS_FILE_ACCESS_UPDATE_EXISTING is also specified.
*/
#define RETRO_VFS_FILE_ACCESS_WRITE (1 << 1)
/**
* Opens a file for reading and writing.
* Any existing file at this path will be discarded and overwritten
* unless \c RETRO_VFS_FILE_ACCESS_UPDATE_EXISTING is also specified.
*/
#define RETRO_VFS_FILE_ACCESS_READ_WRITE (RETRO_VFS_FILE_ACCESS_READ | RETRO_VFS_FILE_ACCESS_WRITE)
/**
* Opens a file without discarding its existing contents.
* Only meaningful if \c RETRO_VFS_FILE_ACCESS_WRITE is specified.
*/
#define RETRO_VFS_FILE_ACCESS_UPDATE_EXISTING (1 << 2) /* Prevents discarding content of existing files opened for writing */
/** @} */
/** @defgroup RETRO_VFS_FILE_ACCESS_HINT File Access Hints
*
* Hints to the frontend for how a file will be accessed.
* The VFS implementation may use these to optimize performance,
* react to external interference (such as concurrent writes),
* or it may ignore them entirely.
*
* Hint flags do not change the behavior of each VFS function
* unless otherwise noted.
* @{
*/
/** No particular hints are given. */
#define RETRO_VFS_FILE_ACCESS_HINT_NONE (0)
/**
* Indicates that the file will be accessed frequently.
*
* The frontend should cache it or map it into memory.
*/
#define RETRO_VFS_FILE_ACCESS_HINT_FREQUENT_ACCESS (1 << 0)
/** @} */
/** @defgroup RETRO_VFS_SEEK_POSITION File Seek Positions
* File access flags and hints.
* @{
*/
/**
* Indicates a seek relative to the start of the file.
*/
#define RETRO_VFS_SEEK_POSITION_START 0
/**
* Indicates a seek relative to the current stream position.
*/
#define RETRO_VFS_SEEK_POSITION_CURRENT 1
/**
* Indicates a seek relative to the end of the file.
* @note The offset passed to \c retro_vfs_seek_t should be negative.
*/
#define RETRO_VFS_SEEK_POSITION_END 2
/** @} */
/** @defgroup RETRO_VFS_STAT File Status Flags
* File stat flags.
* @see retro_vfs_stat_t
* @since VFS API v3
* @{
*/
/** Indicates that the given path refers to a valid file. */
#define RETRO_VFS_STAT_IS_VALID (1 << 0)
/** Indicates that the given path refers to a directory. */
#define RETRO_VFS_STAT_IS_DIRECTORY (1 << 1)
/**
* Indicates that the given path refers to a character special file,
* such as \c /dev/null.
*/
#define RETRO_VFS_STAT_IS_CHARACTER_SPECIAL (1 << 2)
/** @} */
/**
* Returns the path that was used to open this file.
*
* @param stream The opened file handle to get the path of.
* Behavior is undefined if \c NULL or closed.
* @return The path that was used to open \c stream.
* The string is owned by \c stream and must not be modified.
* @since VFS API v1
* @see filestream_get_path
*/
typedef const char *(RETRO_CALLCONV *retro_vfs_get_path_t)(struct retro_vfs_file_handle *stream);
/**
* Open a file for reading or writing.
*
* @param path The path to open.
* @param mode A bitwise combination of \c RETRO_VFS_FILE_ACCESS flags.
* At a minimum, one of \c RETRO_VFS_FILE_ACCESS_READ or \c RETRO_VFS_FILE_ACCESS_WRITE must be specified.
* @param hints A bitwise combination of \c RETRO_VFS_FILE_ACCESS_HINT flags.
* @return A handle to the opened file,
* or \c NULL upon failure.
* Note that this will return \c NULL if \c path names a directory.
* The returned file handle must be closed with \c retro_vfs_close_t.
* @since VFS API v1
* @see File Paths
* @see RETRO_VFS_FILE_ACCESS
* @see RETRO_VFS_FILE_ACCESS_HINT
* @see retro_vfs_close_t
* @see filestream_open
*/
typedef struct retro_vfs_file_handle *(RETRO_CALLCONV *retro_vfs_open_t)(const char *path, unsigned mode, unsigned hints);
/**
* Close the file and release its resources.
* All files returned by \c retro_vfs_open_t must be closed with this function.
*
* @param stream The file handle to close.
* Behavior is undefined if already closed.
* Upon completion of this function, \c stream is no longer valid
* (even if it returns failure).
* @return 0 on success, -1 on failure or if \c stream is \c NULL.
* @see retro_vfs_open_t
* @see filestream_close
* @since VFS API v1
*/
typedef int (RETRO_CALLCONV *retro_vfs_close_t)(struct retro_vfs_file_handle *stream);
/**
* Return the size of the file in bytes.
*
* @param stream The file to query the size of.
* @return Size of the file in bytes, or -1 if there was an error.
* @see filestream_get_size
* @since VFS API v1
*/
typedef int64_t (RETRO_CALLCONV *retro_vfs_size_t)(struct retro_vfs_file_handle *stream);
/**
* Set the file's length.
*
* @param stream The file whose length will be adjusted.
* @param length The new length of the file, in bytes.
* If shorter than the original length, the extra bytes will be discarded.
* If longer, the file's padding is unspecified (and likely platform-dependent).
* @return 0 on success,
* -1 on failure.
* @see filestream_truncate
* @since VFS API v2
*/
typedef int64_t (RETRO_CALLCONV *retro_vfs_truncate_t)(struct retro_vfs_file_handle *stream, int64_t length);
/**
* Gets the given file's current read/write position.
* This position is advanced with each call to \c retro_vfs_read_t or \c retro_vfs_write_t.
*
* @param stream The file to query the position of.
* @return The current stream position in bytes
* or -1 if there was an error.
* @see filestream_tell
* @since VFS API v1
*/
typedef int64_t (RETRO_CALLCONV *retro_vfs_tell_t)(struct retro_vfs_file_handle *stream);
/**
* Sets the given file handle's current read/write position.
*
* @param stream The file to set the position of.
* @param offset The new position, in bytes.
* @param seek_position The position to seek from.
* @return The new position,
* or -1 if there was an error.
* @since VFS API v1
* @see File Seek Positions
* @see filestream_seek
*/
typedef int64_t (RETRO_CALLCONV *retro_vfs_seek_t)(struct retro_vfs_file_handle *stream, int64_t offset, int seek_position);
/**
* Read data from a file, if it was opened for reading.
*
* @param stream The file to read from.
* @param s The buffer to read into.
* @param len The number of bytes to read.
* The buffer pointed to by \c s must be this large.
* @return The number of bytes read,
* or -1 if there was an error.
* @since VFS API v1
* @see filestream_read
*/
typedef int64_t (RETRO_CALLCONV *retro_vfs_read_t)(struct retro_vfs_file_handle *stream, void *s, uint64_t len);
/**
* Write data to a file, if it was opened for writing.
*
* @param stream The file handle to write to.
* @param s The buffer to write from.
* @param len The number of bytes to write.
* The buffer pointed to by \c s must be this large.
* @return The number of bytes written,
* or -1 if there was an error.
* @since VFS API v1
* @see filestream_write
*/
typedef int64_t (RETRO_CALLCONV *retro_vfs_write_t)(struct retro_vfs_file_handle *stream, const void *s, uint64_t len);
/**
* Flush pending writes to the file, if applicable.
*
* This does not mean that the changes will be immediately persisted to disk;
* that may be scheduled for later, depending on the platform.
*
* @param stream The file handle to flush.
* @return 0 on success, -1 on failure.
* @since VFS API v1
* @see filestream_flush
*/
typedef int (RETRO_CALLCONV *retro_vfs_flush_t)(struct retro_vfs_file_handle *stream);
/**
* Deletes the file at the given path.
*
* @param path The path to the file that will be deleted.
* @return 0 on success, -1 on failure.
* @see filestream_delete
* @since VFS API v1
*/
typedef int (RETRO_CALLCONV *retro_vfs_remove_t)(const char *path);
/**
* Rename the specified file.
*
* @param old_path Path to an existing file.
* @param new_path The destination path.
* Must not name an existing file.
* @return 0 on success, -1 on failure
* @see filestream_rename
* @since VFS API v1
*/
typedef int (RETRO_CALLCONV *retro_vfs_rename_t)(const char *old_path, const char *new_path);
/**
* Gets information about the given file.
*
* @param path The path to the file to query.
* @param[out] size The reported size of the file in bytes.
* May be \c NULL, in which case this value is ignored.
* @return A bitmask of \c RETRO_VFS_STAT flags,
* or 0 if \c path doesn't refer to a valid file.
* @see path_stat
* @see path_get_size
* @see RETRO_VFS_STAT
* @since VFS API v3
*/
typedef int (RETRO_CALLCONV *retro_vfs_stat_t)(const char *path, int32_t *size);
/**
* Creates a directory at the given path.
*
* @param dir The desired location of the new directory.
* @return 0 if the directory was created,
* -2 if the directory already exists,
* or -1 if some other error occurred.
* @see path_mkdir
* @since VFS API v3
*/
typedef int (RETRO_CALLCONV *retro_vfs_mkdir_t)(const char *dir);
/**
* Opens a handle to a directory so its contents can be inspected.
*
* @param dir The path to the directory to open.
* Must be an existing directory.
* @param include_hidden Whether to include hidden files in the directory listing.
* The exact semantics of this flag will depend on the platform.
* @return A handle to the opened directory,
* or \c NULL if there was an error.
* @see retro_opendir
* @since VFS API v3
*/
typedef struct retro_vfs_dir_handle *(RETRO_CALLCONV *retro_vfs_opendir_t)(const char *dir, bool include_hidden);
/**
* Gets the next dirent ("directory entry")
* within the given directory.
*
* @param[in,out] dirstream The directory to read from.
* Updated to point to the next file, directory, or other path.
* @return \c true when the next dirent was retrieved,
* \c false if there are no more dirents to read.
* @note This API iterates over all files and directories within \c dirstream.
* Remember to check what the type of the current dirent is.
* @note This function does not recurse,
* i.e. it does not return the contents of subdirectories.
* @note This may include "." and ".." on Unix-like platforms.
* @see retro_readdir
* @see retro_vfs_dirent_is_dir_t
* @since VFS API v3
*/
typedef bool (RETRO_CALLCONV *retro_vfs_readdir_t)(struct retro_vfs_dir_handle *dirstream);
/**
* Gets the filename of the current dirent.
*
* The returned string pointer is valid
* until the next call to \c retro_vfs_readdir_t or \c retro_vfs_closedir_t.
*
* @param dirstream The directory to read from.
* @return The current dirent's name,
* or \c NULL if there was an error.
* @note This function only returns the file's \em name,
* not a complete path to it.
* @see retro_dirent_get_name
* @since VFS API v3
*/
typedef const char *(RETRO_CALLCONV *retro_vfs_dirent_get_name_t)(struct retro_vfs_dir_handle *dirstream);
/**
* Checks whether the current dirent names a directory.
*
* @param dirstream The directory to read from.
* @return \c true if \c dirstream's current dirent points to a directory,
* \c false if not or if there was an error.
* @see retro_dirent_is_dir
* @since VFS API v3
*/
typedef bool (RETRO_CALLCONV *retro_vfs_dirent_is_dir_t)(struct retro_vfs_dir_handle *dirstream);
/**
* Closes the given directory and release its resources.
*
* Must be called on any \c retro_vfs_dir_handle returned by \c retro_vfs_open_t.
*
* @param dirstream The directory to close.
* When this function returns (even failure),
* \c dirstream will no longer be valid and must not be used.
* @return 0 on success, -1 on failure.
* @see retro_closedir
* @since VFS API v3
*/
typedef int (RETRO_CALLCONV *retro_vfs_closedir_t)(struct retro_vfs_dir_handle *dirstream);
/**
* File system interface exposed by the frontend.
*
* @see dirent_vfs_init
* @see filestream_vfs_init
* @see path_vfs_init
* @see RETRO_ENVIRONMENT_GET_VFS_INTERFACE
*/
struct retro_vfs_interface
{
/* VFS API v1 */
/** @copydoc retro_vfs_get_path_t */
retro_vfs_get_path_t get_path;
/** @copydoc retro_vfs_open_t */
retro_vfs_open_t open;
/** @copydoc retro_vfs_close_t */
retro_vfs_close_t close;
/** @copydoc retro_vfs_size_t */
retro_vfs_size_t size;
/** @copydoc retro_vfs_tell_t */
retro_vfs_tell_t tell;
/** @copydoc retro_vfs_seek_t */
retro_vfs_seek_t seek;
/** @copydoc retro_vfs_read_t */
retro_vfs_read_t read;
/** @copydoc retro_vfs_write_t */
retro_vfs_write_t write;
/** @copydoc retro_vfs_flush_t */
retro_vfs_flush_t flush;
/** @copydoc retro_vfs_remove_t */
retro_vfs_remove_t remove;
/** @copydoc retro_vfs_rename_t */
retro_vfs_rename_t rename;
/* VFS API v2 */
/** @copydoc retro_vfs_truncate_t */
retro_vfs_truncate_t truncate;
/* VFS API v3 */
/** @copydoc retro_vfs_stat_t */
retro_vfs_stat_t stat;
/** @copydoc retro_vfs_mkdir_t */
retro_vfs_mkdir_t mkdir;
/** @copydoc retro_vfs_opendir_t */
retro_vfs_opendir_t opendir;
/** @copydoc retro_vfs_readdir_t */
retro_vfs_readdir_t readdir;
/** @copydoc retro_vfs_dirent_get_name_t */
retro_vfs_dirent_get_name_t dirent_get_name;
/** @copydoc retro_vfs_dirent_is_dir_t */
retro_vfs_dirent_is_dir_t dirent_is_dir;
/** @copydoc retro_vfs_closedir_t */
retro_vfs_closedir_t closedir;
};
/**
* Represents a request by the core for the frontend's file system interface,
* as well as the interface itself returned by the frontend.
*
* You do not need to use these functions directly;
* you may pass this struct to \c dirent_vfs_init,
* \c filestream_vfs_init, or \c path_vfs_init
* so that you can use the wrappers provided by these modules.
*
* @see dirent_vfs_init
* @see filestream_vfs_init
* @see path_vfs_init
* @see RETRO_ENVIRONMENT_GET_VFS_INTERFACE
*/
struct retro_vfs_interface_info
{
/**
* The minimum version of the VFS API that the core requires.
* libretro-common's wrapper API initializers will check this value as well.
*
* Set to the core's desired VFS version when requesting an interface,
* and set by the frontend to indicate its actual API version.
*
* If the core asks for a newer VFS API version than the frontend supports,
* the frontend must return \c false within the \c RETRO_ENVIRONMENT_GET_VFS_INTERFACE call.
* @since VFS API v1
*/
uint32_t required_interface_version;
/**
* Set by the frontend.
* The frontend will set this to the VFS interface it provides.
*
* The interface is owned by the frontend
* and must not be modified or freed by the core.
* @since VFS API v1 */
struct retro_vfs_interface *iface;
};
/** @} */
/** @defgroup GET_HW_RENDER_INTERFACE Hardware Rendering Interface
* @{
*/
/**
* Describes the hardware rendering API supported by
* a particular subtype of \c retro_hw_render_interface.
*
* Not every rendering API supported by libretro has its own interface,
* or even needs one.
*
* @see RETRO_ENVIRONMENT_SET_HW_RENDER
* @see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE
*/
enum retro_hw_render_interface_type
{
/**
* Indicates a \c retro_hw_render_interface for Vulkan.
* @see retro_hw_render_interface_vulkan
*/
RETRO_HW_RENDER_INTERFACE_VULKAN = 0,
/** Indicates a \c retro_hw_render_interface for Direct3D 9. */
RETRO_HW_RENDER_INTERFACE_D3D9 = 1,
/** Indicates a \c retro_hw_render_interface for Direct3D 10. */
RETRO_HW_RENDER_INTERFACE_D3D10 = 2,
/**
* Indicates a \c retro_hw_render_interface for Direct3D 11.
* @see retro_hw_render_interface_d3d11
*/
RETRO_HW_RENDER_INTERFACE_D3D11 = 3,
/**
* Indicates a \c retro_hw_render_interface for Direct3D 12.
* @see retro_hw_render_interface_d3d12
*/
RETRO_HW_RENDER_INTERFACE_D3D12 = 4,
/**
* Indicates a \c retro_hw_render_interface for
* the PlayStation's 2 PSKit API.
* @see retro_hw_render_interface_gskit_ps2
*/
RETRO_HW_RENDER_INTERFACE_GSKIT_PS2 = 5,
/** @private Defined to ensure <tt>sizeof(retro_hw_render_interface_type) == sizeof(int)</tt>.
* Do not use. */
RETRO_HW_RENDER_INTERFACE_DUMMY = INT_MAX
};
/**
* Base render interface type.
* All \c retro_hw_render_interface implementations
* will start with these two fields set to particular values.
*
* @see retro_hw_render_interface_type
* @see RETRO_ENVIRONMENT_SET_HW_RENDER
* @see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE
*/
struct retro_hw_render_interface
{
/**
* Denotes the particular rendering API that this interface is for.
* Each interface requires this field to be set to a particular value.
* Use it to cast this interface to the appropriate pointer.
*/
enum retro_hw_render_interface_type interface_type;
/**
* The version of this rendering interface.
* @note This is not related to the version of the API itself.
*/
unsigned interface_version;
};
/** @} */
/**
* @defgroup GET_LED_INTERFACE LED Interface
* @{
*/
/** @copydoc retro_led_interface::set_led_state */
typedef void (RETRO_CALLCONV *retro_set_led_state_t)(int led, int state);
/**
* Interface that the core can use to set the state of available LEDs.
* @see RETRO_ENVIRONMENT_GET_LED_INTERFACE
*/
struct retro_led_interface
{
/**
* Sets the state of an LED.
*
* @param led The LED to set the state of.
* @param state The state to set the LED to.
* \c true to enable, \c false to disable.
*/
retro_set_led_state_t set_led_state;
};
/** @} */
/** @defgroup GET_AUDIO_VIDEO_ENABLE Skipped A/V Steps
* @{
*/
/**
* Flags that define A/V steps that the core may skip for this frame.
*
* @see RETRO_ENVIRONMENT_GET_AUDIO_VIDEO_ENABLE
*/
enum retro_av_enable_flags
{
/**
* If set, the core should render video output with \c retro_video_refresh_t as normal.
*
* Otherwise, the frontend will discard any video data received this frame,
* including frames presented via hardware acceleration.
* \c retro_video_refresh_t will do nothing.
*
* @note After running the frame, the video output of the next frame
* should be no different than if video was enabled,
* and saving and loading state should have no issues.
* This implies that the emulated console's graphics pipeline state
* should not be affected by this flag.
*
* @note If emulating a platform that supports display capture
* (i.e. reading its own VRAM),
* the core may not be able to completely skip rendering,
* as the VRAM is part of the graphics pipeline's state.
*/
RETRO_AV_ENABLE_VIDEO = (1 << 0),
/**
* If set, the core should render audio output
* with \c retro_audio_sample_t or \c retro_audio_sample_batch_t as normal.
*
* Otherwise, the frontend will discard any audio data received this frame.
* The core should skip audio rendering if possible.
*
* @note After running the frame, the audio output of the next frame
* should be no different than if audio was enabled,
* and saving and loading state should have no issues.
* This implies that the emulated console's audio pipeline state
* should not be affected by this flag.
*/
RETRO_AV_ENABLE_AUDIO = (1 << 1),
/**
* If set, indicates that any savestates taken this frame
* are guaranteed to be created by the same binary that will load them,
* and will not be written to or read from the disk.
*
* The core may use these guarantees to:
*
* @li Assume that loading state will succeed.
* @li Update its memory buffers in-place if possible.
* @li Skip clearing memory.
* @li Skip resetting the system.
* @li Skip validation steps.
*
* @deprecated Use \c RETRO_ENVIRONMENT_GET_SAVESTATE_CONTEXT instead,
* except for compatibility purposes.
*/
RETRO_AV_ENABLE_FAST_SAVESTATES = (1 << 2),
/**
* If set, indicates that the frontend will never need audio from the core.
* Used by a frontend for implementing runahead via a secondary core instance.
*
* The core may stop synthesizing audio if it can do so
* without compromising emulation accuracy.
*
* Audio output for the next frame does not matter,
* and the frontend will never need an accurate audio state in the future.
*
* State will never be saved while this flag is set.
*/
RETRO_AV_ENABLE_HARD_DISABLE_AUDIO = (1 << 3),
/**
* @private Defined to ensure <tt>sizeof(retro_av_enable_flags) == sizeof(int)</tt>.
* Do not use.
*/
RETRO_AV_ENABLE_DUMMY = INT_MAX
};
/** @} */
/**
* @defgroup GET_MIDI_INTERFACE MIDI Interface
* @{
*/
/** @copydoc retro_midi_interface::input_enabled */
typedef bool (RETRO_CALLCONV *retro_midi_input_enabled_t)(void);
/** @copydoc retro_midi_interface::output_enabled */
typedef bool (RETRO_CALLCONV *retro_midi_output_enabled_t)(void);
/** @copydoc retro_midi_interface::read */
typedef bool (RETRO_CALLCONV *retro_midi_read_t)(uint8_t *byte);
/** @copydoc retro_midi_interface::write */
typedef bool (RETRO_CALLCONV *retro_midi_write_t)(uint8_t byte, uint32_t delta_time);
/** @copydoc retro_midi_interface::flush */
typedef bool (RETRO_CALLCONV *retro_midi_flush_t)(void);
/**
* Interface that the core can use for raw MIDI I/O.
*/
struct retro_midi_interface
{
/**
* Retrieves the current state of MIDI input.
*
* @return \c true if MIDI input is enabled.
*/
retro_midi_input_enabled_t input_enabled;
/**
* Retrieves the current state of MIDI output.
* @return \c true if MIDI output is enabled.
*/
retro_midi_output_enabled_t output_enabled;
/**
* Reads a byte from the MIDI input stream.
*
* @param[out] byte The byte received from the input stream.
* @return \c true if a byte was read,
* \c false if MIDI input is disabled or \c byte is \c NULL.
*/
retro_midi_read_t read;
/**
* Writes a byte to the output stream.
*
* @param byte The byte to write to the output stream.
* @param delta_time Time since the previous write, in microseconds.
* @return \c true if c\ byte was written, false otherwise.
*/
retro_midi_write_t write;
/**
* Flushes previously-written data.
*
* @return \c true if successful.
*/
retro_midi_flush_t flush;
};
/** @} */
/** @defgroup SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE Render Context Negotiation
* @{
*/
/**
* Describes the hardware rendering API used by
* a particular subtype of \c retro_hw_render_context_negotiation_interface.
*
* Not every rendering API supported by libretro has a context negotiation interface,
* or even needs one.
*
* @see RETRO_ENVIRONMENT_SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE
* @see RETRO_ENVIRONMENT_SET_HW_RENDER
* @see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE
*/
enum retro_hw_render_context_negotiation_interface_type
{
/**
* Denotes a context negotiation interface for Vulkan.
* @see retro_hw_render_context_negotiation_interface_vulkan
*/
RETRO_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_VULKAN = 0,
/**
* @private Defined to ensure <tt>sizeof(retro_hw_render_context_negotiation_interface_type) == sizeof(int)</tt>.
* Do not use.
*/
RETRO_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_DUMMY = INT_MAX
};
/**
* Base context negotiation interface type.
* All \c retro_hw_render_context_negotiation_interface implementations
* will start with these two fields set to particular values.
*
* @see retro_hw_render_interface_type
* @see RETRO_ENVIRONMENT_SET_HW_RENDER
* @see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE
* @see RETRO_ENVIRONMENT_SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE
*/
struct retro_hw_render_context_negotiation_interface
{
/**
* Denotes the particular rendering API that this interface is for.
* Each interface requires this field to be set to a particular value.
* Use it to cast this interface to the appropriate pointer.
*/
enum retro_hw_render_context_negotiation_interface_type interface_type;
/**
* The version of this negotiation interface.
* @note This is not related to the version of the API itself.
*/
unsigned interface_version;
};
/** @} */
/** @defgroup RETRO_SERIALIZATION_QUIRK Serialization Quirks
* @{
*/
/**
* Indicates that serialized state is incomplete in some way.
*
* Set if serialization is usable for the common case of saving and loading game state,
* but should not be relied upon for frame-sensitive frontend features
* such as netplay or rerecording.
*/
#define RETRO_SERIALIZATION_QUIRK_INCOMPLETE (1 << 0)
/**
* Indicates that core must spend some time initializing before serialization can be done.
*
* \c retro_serialize(), \c retro_unserialize(), and \c retro_serialize_size() will initially fail.
*/
#define RETRO_SERIALIZATION_QUIRK_MUST_INITIALIZE (1 << 1)
/** Set by the core to indicate that serialization size may change within a session. */
#define RETRO_SERIALIZATION_QUIRK_CORE_VARIABLE_SIZE (1 << 2)
/** Set by the frontend to acknowledge that it supports variable-sized states. */
#define RETRO_SERIALIZATION_QUIRK_FRONT_VARIABLE_SIZE (1 << 3)
/** Serialized state can only be loaded during the same session. */
#define RETRO_SERIALIZATION_QUIRK_SINGLE_SESSION (1 << 4)
/**
* Serialized state cannot be loaded on an architecture
* with a different endianness from the one it was saved on.
*/
#define RETRO_SERIALIZATION_QUIRK_ENDIAN_DEPENDENT (1 << 5)
/**
* Serialized state cannot be loaded on a different platform
* from the one it was saved on for reasons other than endianness,
* such as word size dependence.
*/
#define RETRO_SERIALIZATION_QUIRK_PLATFORM_DEPENDENT (1 << 6)
/** @} */
/** @defgroup SET_MEMORY_MAPS Memory Descriptors
* @{
*/
/** @defgroup RETRO_MEMDESC Memory Descriptor Flags
* Information about how the emulated hardware uses this portion of its address space.
* @{
*/
/**
* Indicates that this memory area won't be modified
* once \c retro_load_game has returned.
*/
#define RETRO_MEMDESC_CONST (1 << 0)
/**
* Indicates a memory area with big-endian byte ordering,
* as opposed to the default of little-endian.
*/
#define RETRO_MEMDESC_BIGENDIAN (1 << 1)
/**
* Indicates a memory area that is used for the emulated system's main RAM.
*/
#define RETRO_MEMDESC_SYSTEM_RAM (1 << 2)
/**
* Indicates a memory area that is used for the emulated system's save RAM,
* usually found on a game cartridge as battery-backed RAM or flash memory.
*/
#define RETRO_MEMDESC_SAVE_RAM (1 << 3)
/**
* Indicates a memory area that is used for the emulated system's video RAM,
* usually found on a console's GPU (or local equivalent).
*/
#define RETRO_MEMDESC_VIDEO_RAM (1 << 4)
/**
* Indicates a memory area that requires all accesses
* to be aligned to 2 bytes or their own size
* (whichever is smaller).
*/
#define RETRO_MEMDESC_ALIGN_2 (1 << 16)
/**
* Indicates a memory area that requires all accesses
* to be aligned to 4 bytes or their own size
* (whichever is smaller).
*/
#define RETRO_MEMDESC_ALIGN_4 (2 << 16)
/**
* Indicates a memory area that requires all accesses
* to be aligned to 8 bytes or their own size
* (whichever is smaller).
*/
#define RETRO_MEMDESC_ALIGN_8 (3 << 16)
/**
* Indicates a memory area that requires all accesses
* to be at least 2 bytes long.
*/
#define RETRO_MEMDESC_MINSIZE_2 (1 << 24)
/**
* Indicates a memory area that requires all accesses
* to be at least 4 bytes long.
*/
#define RETRO_MEMDESC_MINSIZE_4 (2 << 24)
/**
* Indicates a memory area that requires all accesses
* to be at least 8 bytes long.
*/
#define RETRO_MEMDESC_MINSIZE_8 (3 << 24)
/** @} */
/**
* A mapping from a region of the emulated console's address space
* to the host's address space.
*
* Can be used to map an address in the console's address space
* to the host's address space, like so:
*
* @code
* void* emu_to_host(void* addr, struct retro_memory_descriptor* descriptor)
* {
* return descriptor->ptr + (addr & ~descriptor->disconnect) - descriptor->start;
* }
* @endcode
*
* @see RETRO_ENVIRONMENT_SET_MEMORY_MAPS
*/
struct retro_memory_descriptor
{
/**
* A bitwise \c OR of one or more \ref RETRO_MEMDESC "flags"
* that describe how the emulated system uses this descriptor's address range.
*
* @note If \c ptr is \c NULL,
* then no flags should be set.
* @see RETRO_MEMDESC
*/
uint64_t flags;
/**
* Pointer to the start of this memory region's buffer
* within the \em host's address space.
* The address listed here must be valid for the duration of the session;
* it must not be freed or modified by the frontend
* and it must not be moved by the core.
*
* May be \c NULL to indicate a lack of accessible memory
* at the emulated address given in \c start.
*
* @note Overlapping descriptors that include the same byte
* must have the same \c ptr value.
*/
void *ptr;
/**
* The offset of this memory region,
* relative to the address given by \c ptr.
*
* @note It is recommended to use this field for address calculations
* instead of performing arithmetic on \c ptr.
*/
size_t offset;
/**
* The starting address of this memory region
* <em>within the emulated hardware's address space</em>.
*
* @note Not represented as a pointer
* because it's unlikely to be valid on the host device.
*/
size_t start;
/**
* A bitmask that specifies which bits of an address must match
* the bits of the \ref start address.
*
* Combines with \c disconnect to map an address to a memory block.
*
* If multiple memory descriptors can claim a particular byte,
* the first one defined in the \ref retro_memory_descriptor array applies.
* A bit which is set in \c start must also be set in this.
*
* Can be zero, in which case \c start and \c len represent
* the complete mapping for this region of memory
* (i.e. each byte is mapped exactly once).
* In this case, \c len must be a power of two.
*/
size_t select;
/**
* A bitmask of bits that are \em not used for addressing.
*
* Any set bits are assumed to be disconnected from
* the emulated memory chip's address pins,
* and are therefore ignored when memory-mapping.
*/
size_t disconnect;
/**
* The length of this memory region, in bytes.
*
* If applying \ref start and \ref disconnect to an address
* results in a value higher than this,
* the highest bit of the address is cleared.
*
* If the address is still too high, the next highest bit is cleared.
* Can be zero, in which case it's assumed to be
* bounded only by \ref select and \ref disconnect.
*/
size_t len;
/**
* A short name for this address space.
*
* Names must meet the following requirements:
*
* \li Characters must be in the set <tt>[a-zA-Z0-9_-]</tt>.
* \li No more than 8 characters, plus a \c NULL terminator.
* \li Names are case-sensitive, but lowercase characters are discouraged.
* \li A name must not be the same as another name plus a character in the set \c [A-F0-9]
* (i.e. if an address space named "RAM" exists,
* then the names "RAM0", "RAM1", ..., "RAMF" are forbidden).
* This is to allow addresses to be named by each descriptor unambiguously,
* even if the areas overlap.
* \li May be \c NULL or empty (both are considered equivalent).
*
* Here are some examples of pairs of address space names:
*
* \li \em blank + \em blank: valid (multiple things may be mapped in the same namespace)
* \li \c Sp + \c Sp: valid (multiple things may be mapped in the same namespace)
* \li \c SRAM + \c VRAM: valid (neither is a prefix of the other)
* \li \c V + \em blank: valid (\c V is not in \c [A-F0-9])
* \li \c a + \em blank: valid but discouraged (\c a is not in \c [A-F0-9])
* \li \c a + \c A: valid but discouraged (neither is a prefix of the other)
* \li \c AR + \em blank: valid (\c R is not in \c [A-F0-9])
* \li \c ARB + \em blank: valid (there's no \c AR namespace,
* so the \c B doesn't cause ambiguity).
* \li \em blank + \c B: invalid, because it's ambiguous which address space \c B1234 would refer to.
*
* The length of the address space's name can't be used to disambugiate,
* as extra information may be appended to it without a separator.
*/
const char *addrspace;
/* TODO: When finalizing this one, add a description field, which should be
* "WRAM" or something roughly equally long. */
/* TODO: When finalizing this one, replace 'select' with 'limit', which tells
* which bits can vary and still refer to the same address (limit = ~select).
* TODO: limit? range? vary? something else? */
/* TODO: When finalizing this one, if 'len' is above what 'select' (or
* 'limit') allows, it's bankswitched. Bankswitched data must have both 'len'
* and 'select' != 0, and the mappings don't tell how the system switches the
* banks. */
/* TODO: When finalizing this one, fix the 'len' bit removal order.
* For len=0x1800, pointer 0x1C00 should go to 0x1400, not 0x0C00.
* Algorithm: Take bits highest to lowest, but if it goes above len, clear
* the most recent addition and continue on the next bit.
* TODO: Can the above be optimized? Is "remove the lowest bit set in both
* pointer and 'len'" equivalent? */
/* TODO: Some emulators (MAME?) emulate big endian systems by only accessing
* the emulated memory in 32-bit chunks, native endian. But that's nothing
* compared to Darek Mihocka <http://www.emulators.com/docs/nx07_vm101.htm>
* (section Emulation 103 - Nearly Free Byte Reversal) - he flips the ENTIRE
* RAM backwards! I'll want to represent both of those, via some flags.
*
* I suspect MAME either didn't think of that idea, or don't want the #ifdef.
* Not sure which, nor do I really care. */
/* TODO: Some of those flags are unused and/or don't really make sense. Clean
* them up. */
};
/**
* A list of regions within the emulated console's address space.
*
* The frontend may use the largest value of
* \ref retro_memory_descriptor::start + \ref retro_memory_descriptor::select
* in a certain namespace to infer the overall size of the address space.
* If the address space is larger than that,
* the last mapping in \ref descriptors should have \ref retro_memory_descriptor::ptr set to \c NULL
* and \ref retro_memory_descriptor::select should have all bits used in the address space set to 1.
*
* Here's an example set of descriptors for the SNES.
*
* @code{.c}
* struct retro_memory_map snes_descriptors = retro_memory_map
* {
* .descriptors = (struct retro_memory_descriptor[])
* {
* // WRAM; must usually be mapped before the ROM,
* // as some SNES ROM mappers try to claim 0x7E0000
* { .addrspace="WRAM", .start=0x7E0000, .len=0x20000 },
*
* // SPC700 RAM
* { .addrspace="SPC700", .len=0x10000 },
*
* // WRAM mirrors
* { .addrspace="WRAM", .start=0x000000, .select=0xC0E000, .len=0x2000 },
* { .addrspace="WRAM", .start=0x800000, .select=0xC0E000, .len=0x2000 },
*
* // WRAM mirror, alternate equivalent descriptor
* // (Various similar constructions can be created by combining parts of the above two.)
* { .addrspace="WRAM", .select=0x40E000, .disconnect=~0x1FFF },
*
* // LoROM (512KB, mirrored a couple of times)
* { .addrspace="LoROM", .start=0x008000, .select=0x408000, .disconnect=0x8000, .len=512*1024, .flags=RETRO_MEMDESC_CONST },
* { .addrspace="LoROM", .start=0x400000, .select=0x400000, .disconnect=0x8000, .len=512*1024, .flags=RETRO_MEMDESC_CONST },
*
* // HiROM (4MB)
* { .addrspace="HiROM", .start=0x400000, .select=0x400000, .len=4*1024*1024, .flags=RETRO_MEMDESC_CONST },
* { .addrspace="HiROM", .start=0x008000, .select=0x408000, .len=4*1024*1024, .offset=0x8000, .flags=RETRO_MEMDESC_CONST },
*
* // ExHiROM (8MB)
* { .addrspace="ExHiROM", .start=0xC00000, .select=0xC00000, .len=4*1024*1024, .offset=0, .flags=RETRO_MEMDESC_CONST },
* { .addrspace="ExHiROM", .start=0x400000, .select=0xC00000, .len=4*1024*1024, .offset=4*1024*1024, .flags=RETRO_MEMDESC_CONST },
* { .addrspace="ExHiROM", .start=0x808000, .select=0xC08000, .len=4*1024*1024, .offset=0x8000, .flags=RETRO_MEMDESC_CONST },
* { .addrspace="ExHiROM", .start=0x008000, .select=0xC08000, .len=4*1024*1024, .offset=4*1024*1024+0x8000, .flags=RETRO_MEMDESC_CONST },
*
* // Clarifying the full size of the address space
* { .select=0xFFFFFF, .ptr=NULL },
* },
* .num_descriptors = 14,
* };
* @endcode
*
* @see RETRO_ENVIRONMENT_SET_MEMORY_MAPS
*/
struct retro_memory_map
{
/**
* Pointer to an array of memory descriptors,
* each of which describes part of the emulated console's address space.
*/
const struct retro_memory_descriptor *descriptors;
/** The number of descriptors in \c descriptors. */
unsigned num_descriptors;
};
/** @} */
/** @defgroup SET_CONTROLLER_INFO Controller Info
* @{
*/
/**
* Details about a controller (or controller configuration)
* supported by one of a core's emulated input ports.
*
* @see RETRO_ENVIRONMENT_SET_CONTROLLER_INFO
*/
struct retro_controller_description
{
/**
* A human-readable label for the controller or configuration
* represented by this device type.
* Most likely the device's original brand name.
*/
const char *desc;
/**
* A unique identifier that will be passed to \c retro_set_controller_port_device()'s \c device parameter.
* May be the ID of one of \ref RETRO_DEVICE "the generic controller types",
* or a subclass ID defined with \c RETRO_DEVICE_SUBCLASS.
*
* @see RETRO_DEVICE_SUBCLASS
*/
unsigned id;
};
/**
* Lists the types of controllers supported by
* one of core's emulated input ports.
*
* @see RETRO_ENVIRONMENT_SET_CONTROLLER_INFO
*/
struct retro_controller_info
{
/**
* A pointer to an array of device types supported by this controller port.
*
* @note Ports that support the same devices
* may share the same underlying array.
*/
const struct retro_controller_description *types;
/** The number of elements in \c types. */
unsigned num_types;
};
/** @} */
/** @defgroup SET_SUBSYSTEM_INFO Subsystems
* @{
*/
/**
* Information about a type of memory associated with a subsystem.
* Usually used for SRAM (save RAM).
*
* @see RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO
* @see retro_get_memory_data
* @see retro_get_memory_size
*/
struct retro_subsystem_memory_info
{
/**
* The file extension the frontend should use
* to save this memory region to disk, e.g. "srm" or "sav".
*/
const char *extension;
/**
* A constant that identifies this type of memory.
* Should be at least 0x100 (256) to avoid conflict
* with the standard libretro memory types,
* unless a subsystem uses the main platform's memory region.
* @see RETRO_MEMORY
*/
unsigned type;
};
/**
* Information about a type of ROM that a subsystem may use.
* Subsystems may use one or more ROMs at once,
* possibly of different types.
*
* @see RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO
* @see retro_subsystem_info
*/
struct retro_subsystem_rom_info
{
/**
* Human-readable description of what the content represents,
* e.g. "Game Boy ROM".
*/
const char *desc;
/** @copydoc retro_system_info::valid_extensions */
const char *valid_extensions;
/** @copydoc retro_system_info::need_fullpath */
bool need_fullpath;
/** @copydoc retro_system_info::block_extract */
bool block_extract;
/**
* Indicates whether this particular subsystem ROM is required.
* If \c true and the user doesn't provide a ROM,
* the frontend should not load the core.
* If \c false and the user doesn't provide a ROM,
* the frontend should pass a zeroed-out \c retro_game_info
* to the corresponding entry in \c retro_load_game_special().
*/
bool required;
/**
* Pointer to an array of memory descriptors that this subsystem ROM type uses.
* Useful for secondary cartridges that have their own save data.
* May be \c NULL, in which case this subsystem ROM's memory is not persisted by the frontend
* and \c num_memory should be zero.
*/
const struct retro_subsystem_memory_info *memory;
/** The number of elements in the array pointed to by \c memory. */
unsigned num_memory;
};
/**
* Information about a secondary platform that a core supports.
* @see RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO
*/
struct retro_subsystem_info
{
/**
* A human-readable description of the subsystem type,
* usually the brand name of the original platform
* (e.g. "Super Game Boy").
*/
const char *desc;
/**
* A short machine-friendly identifier for the subsystem,
* usually an abbreviation of the platform name.
* For example, a Super Game Boy subsystem for a SNES core
* might use an identifier of "sgb".
* This identifier can be used for command-line interfaces,
* configuration, or other purposes.
* Must use lower-case alphabetical characters only (i.e. from a-z).
*/
const char *ident;
/**
* The list of ROM types that this subsystem may use.
*
* The first entry is considered to be the "most significant" content,
* for the purposes of the frontend's categorization.
* E.g. with Super GameBoy, the first content should be the GameBoy ROM,
* as it is the most "significant" content to a user.
*
* If a frontend creates new files based on the content used (e.g. for savestates),
* it should derive the filenames from the name of the first ROM in this list.
*
* @note \c roms can have a single element,
* but this is usually a sign that the core should broaden its
* primary system info instead.
*
* @see \c retro_system_info
*/
const struct retro_subsystem_rom_info *roms;
/** The length of the array given in \c roms. */
unsigned num_roms;
/** A unique identifier passed to retro_load_game_special(). */
unsigned id;
};
/** @} */
/** @defgroup SET_PROC_ADDRESS_CALLBACK Core Function Pointers
* @{ */
/**
* The function pointer type that \c retro_get_proc_address_t returns.
*
* Despite the signature shown here, the original function may include any parameters and return type
* that respects the calling convention and C ABI.
*
* The frontend is expected to cast the function pointer to the correct type.
*/
typedef void (RETRO_CALLCONV *retro_proc_address_t)(void);
/**
* Get a symbol from a libretro core.
*
* Cores should only return symbols that serve as libretro extensions.
* Frontends should not use this to obtain symbols to standard libretro entry points;
* instead, they should link to the core statically or use \c dlsym (or local equivalent).
*
* The symbol name must be equal to the function name.
* e.g. if <tt>void retro_foo(void);</tt> exists, the symbol in the compiled library must be called \c retro_foo.
* The returned function pointer must be cast to the corresponding type.
*
* @param \c sym The name of the symbol to look up.
* @return Pointer to the exposed function with the name given in \c sym,
* or \c NULL if one couldn't be found.
* @note The frontend is expected to know the returned pointer's type in advance
* so that it can be cast correctly.
* @note The core doesn't need to expose every possible function through this interface.
* It's enough to only expose the ones that it expects the frontend to use.
* @note The functions exposed through this interface
* don't need to be publicly exposed in the compiled library
* (e.g. via \c __declspec(dllexport)).
* @see RETRO_ENVIRONMENT_SET_PROC_ADDRESS_CALLBACK
*/
typedef retro_proc_address_t (RETRO_CALLCONV *retro_get_proc_address_t)(const char *sym);
/**
* An interface that the frontend can use to get function pointers from the core.
*
* @note The returned function pointer will be invalidated once the core is unloaded.
* How and when that happens is up to the frontend.
*
* @see retro_get_proc_address_t
* @see RETRO_ENVIRONMENT_SET_PROC_ADDRESS_CALLBACK
*/
struct retro_get_proc_address_interface
{
/** Set by the core. */
retro_get_proc_address_t get_proc_address;
};
/** @} */
/** @defgroup GET_LOG_INTERFACE Logging
* @{
*/
/**
* The severity of a given message.
* The frontend may log messages differently depending on the level.
* It may also ignore log messages of a certain level.
* @see retro_log_callback
*/
enum retro_log_level
{
/** The logged message is most likely not interesting to the user. */
RETRO_LOG_DEBUG = 0,
/** Information about the core operating normally. */
RETRO_LOG_INFO,
/** Indicates a potential problem, possibly one that the core can recover from. */
RETRO_LOG_WARN,
/** Indicates a degraded experience, if not failure. */
RETRO_LOG_ERROR,
/** Defined to ensure that sizeof(enum retro_log_level) == sizeof(int). Do not use. */
RETRO_LOG_DUMMY = INT_MAX
};
/**
* Logs a message to the frontend.
*
* @param level The log level of the message.
* @param fmt The format string to log.
* Same format as \c printf.
* Behavior is undefined if this is \c NULL.
* @param ... Zero or more arguments used by the format string.
* Behavior is undefined if these don't match the ones expected by \c fmt.
* @see retro_log_level
* @see retro_log_callback
* @see RETRO_ENVIRONMENT_GET_LOG_INTERFACE
* @see printf
*/
typedef void (RETRO_CALLCONV *retro_log_printf_t)(enum retro_log_level level,
const char *fmt, ...);
/**
* Details about how to make log messages.
*
* @see retro_log_printf_t
* @see RETRO_ENVIRONMENT_GET_LOG_INTERFACE
*/
struct retro_log_callback
{
/**
* Called when logging a message.
*
* @note Set by the frontend.
*/
retro_log_printf_t log;
};
/** @} */
/** @defgroup GET_PERF_INTERFACE Performance Interface
* @{
*/
/** @defgroup RETRO_SIMD CPU Features
* @{
*/
/**
* Indicates CPU support for the SSE instruction set.
*
* @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSE
*/
#define RETRO_SIMD_SSE (1 << 0)
/**
* Indicates CPU support for the SSE2 instruction set.
*
* @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSE2
*/
#define RETRO_SIMD_SSE2 (1 << 1)
/** Indicates CPU support for the AltiVec (aka VMX or Velocity Engine) instruction set. */
#define RETRO_SIMD_VMX (1 << 2)
/** Indicates CPU support for the VMX128 instruction set. Xbox 360 only. */
#define RETRO_SIMD_VMX128 (1 << 3)
/**
* Indicates CPU support for the AVX instruction set.
*
* @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#avxnewtechs=AVX
*/
#define RETRO_SIMD_AVX (1 << 4)
/**
* Indicates CPU support for the NEON instruction set.
* @see https://developer.arm.com/architectures/instruction-sets/intrinsics/#f:@navigationhierarchiessimdisa=[Neon]
*/
#define RETRO_SIMD_NEON (1 << 5)
/**
* Indicates CPU support for the SSE3 instruction set.
*
* @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSE3
*/
#define RETRO_SIMD_SSE3 (1 << 6)
/**
* Indicates CPU support for the SSSE3 instruction set.
*
* @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSSE3
*/
#define RETRO_SIMD_SSSE3 (1 << 7)
/**
* Indicates CPU support for the MMX instruction set.
* @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#techs=MMX
*/
#define RETRO_SIMD_MMX (1 << 8)
/** Indicates CPU support for the MMXEXT instruction set. */
#define RETRO_SIMD_MMXEXT (1 << 9)
/**
* Indicates CPU support for the SSE4 instruction set.
*
* @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSE4_1
*/
#define RETRO_SIMD_SSE4 (1 << 10)
/**
* Indicates CPU support for the SSE4.2 instruction set.
*
* @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSE4_2
*/
#define RETRO_SIMD_SSE42 (1 << 11)
/**
* Indicates CPU support for the AVX2 instruction set.
*
* @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#avxnewtechs=AVX2
*/
#define RETRO_SIMD_AVX2 (1 << 12)
/** Indicates CPU support for the VFPU instruction set. PS2 and PSP only.
*
* @see https://pspdev.github.io/vfpu-docs
*/
#define RETRO_SIMD_VFPU (1 << 13)
/**
* Indicates CPU support for Gekko SIMD extensions. GameCube only.
*/
#define RETRO_SIMD_PS (1 << 14)
/**
* Indicates CPU support for AES instructions.
*
* @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#aestechs=AES&othertechs=AES
*/
#define RETRO_SIMD_AES (1 << 15)
/**
* Indicates CPU support for the VFPv3 instruction set.
*/
#define RETRO_SIMD_VFPV3 (1 << 16)
/**
* Indicates CPU support for the VFPv4 instruction set.
*/
#define RETRO_SIMD_VFPV4 (1 << 17)
/** Indicates CPU support for the POPCNT instruction. */
#define RETRO_SIMD_POPCNT (1 << 18)
/** Indicates CPU support for the MOVBE instruction. */
#define RETRO_SIMD_MOVBE (1 << 19)
/** Indicates CPU support for the CMOV instruction. */
#define RETRO_SIMD_CMOV (1 << 20)
/** Indicates CPU support for the ASIMD instruction set. */
#define RETRO_SIMD_ASIMD (1 << 21)
/** @} */
/**
* An abstract unit of ticks.
*
* Usually nanoseconds or CPU cycles,
* but it depends on the platform and the frontend.
*/
typedef uint64_t retro_perf_tick_t;
/** Time in microseconds. */
typedef int64_t retro_time_t;
/**
* A performance counter.
*
* Use this to measure the execution time of a region of code.
* @see retro_perf_callback
*/
struct retro_perf_counter
{
/**
* A human-readable identifier for the counter.
*
* May be displayed by the frontend.
* Behavior is undefined if this is \c NULL.
*/
const char *ident;
/**
* The time of the most recent call to \c retro_perf_callback::perf_start
* on this performance counter.
*
* @see retro_perf_start_t
*/
retro_perf_tick_t start;
/**
* The total time spent within this performance counter's measured code,
* i.e. between calls to \c retro_perf_callback::perf_start and \c retro_perf_callback::perf_stop.
*
* Updated after each call to \c retro_perf_callback::perf_stop.
* @see retro_perf_stop_t
*/
retro_perf_tick_t total;
/**
* The number of times this performance counter has been started.
*
* Updated after each call to \c retro_perf_callback::perf_start.
* @see retro_perf_start_t
*/
retro_perf_tick_t call_cnt;
/**
* \c true if this performance counter has been registered by the frontend.
* Must be initialized to \c false by the core before registering it.
* @see retro_perf_register_t
*/
bool registered;
};
/**
* @returns The current system time in microseconds.
* @note Accuracy may vary by platform.
* The frontend should use the most accurate timer possible.
* @see RETRO_ENVIRONMENT_GET_PERF_INTERFACE
*/
typedef retro_time_t (RETRO_CALLCONV *retro_perf_get_time_usec_t)(void);
/**
* @returns The number of ticks since some unspecified epoch.
* The exact meaning of a "tick" depends on the platform,
* but it usually refers to nanoseconds or CPU cycles.
* @see RETRO_ENVIRONMENT_GET_PERF_INTERFACE
*/
typedef retro_perf_tick_t (RETRO_CALLCONV *retro_perf_get_counter_t)(void);
/**
* Returns a bitmask of detected CPU features.
*
* Use this for runtime dispatching of CPU-specific code.
*
* @returns A bitmask of detected CPU features.
* @see RETRO_ENVIRONMENT_GET_PERF_INTERFACE
* @see RETRO_SIMD
*/
typedef uint64_t (RETRO_CALLCONV *retro_get_cpu_features_t)(void);
/**
* Asks the frontend to log or display the state of performance counters.
* How this is done depends on the frontend.
* Performance counters can be reviewed manually as well.
*
* @see RETRO_ENVIRONMENT_GET_PERF_INTERFACE
* @see retro_perf_counter
*/
typedef void (RETRO_CALLCONV *retro_perf_log_t)(void);
/**
* Registers a new performance counter.
*
* If \c counter has already been registered beforehand,
* this function does nothing.
*
* @param counter The counter to register.
* \c counter::ident must be set to a unique identifier,
* and all other values in \c counter must be set to zero or \c false.
* Behavior is undefined if \c NULL.
* @post If \c counter is successfully registered,
* then \c counter::registered will be set to \c true.
* Otherwise, it will be set to \c false.
* Registration may fail if the frontend's maximum number of counters (if any) has been reached.
* @note The counter is owned by the core and must not be freed by the frontend.
* The frontend must also clean up any references to a core's performance counters
* before unloading it, otherwise undefined behavior may occur.
* @see retro_perf_start_t
* @see retro_perf_stop_t
*/
typedef void (RETRO_CALLCONV *retro_perf_register_t)(struct retro_perf_counter *counter);
/**
* Starts a registered performance counter.
*
* Call this just before the code you want to measure.
*
* @param counter The counter to start.
* Behavior is undefined if \c NULL.
* @see retro_perf_stop_t
*/
typedef void (RETRO_CALLCONV *retro_perf_start_t)(struct retro_perf_counter *counter);
/**
* Stops a registered performance counter.
*
* Call this just after the code you want to measure.
*
* @param counter The counter to stop.
* Behavior is undefined if \c NULL.
* @see retro_perf_start_t
* @see retro_perf_stop_t
*/
typedef void (RETRO_CALLCONV *retro_perf_stop_t)(struct retro_perf_counter *counter);
/**
* An interface that the core can use to get performance information.
*
* Here's a usage example:
*
* @code{.c}
* #ifdef PROFILING
* // Wrapper macros to simplify using performance counters.
* // Optional; tailor these to your project's needs.
* #define RETRO_PERFORMANCE_INIT(perf_cb, name) static struct retro_perf_counter name = {#name}; if (!name.registered) perf_cb.perf_register(&(name))
* #define RETRO_PERFORMANCE_START(perf_cb, name) perf_cb.perf_start(&(name))
* #define RETRO_PERFORMANCE_STOP(perf_cb, name) perf_cb.perf_stop(&(name))
* #else
* // Exclude the performance counters if profiling is disabled.
* #define RETRO_PERFORMANCE_INIT(perf_cb, name) ((void)0)
* #define RETRO_PERFORMANCE_START(perf_cb, name) ((void)0)
* #define RETRO_PERFORMANCE_STOP(perf_cb, name) ((void)0)
* #endif
*
* // Defined somewhere else in the core.
* extern struct retro_perf_callback perf_cb;
*
* void retro_run(void)
* {
* RETRO_PERFORMANCE_INIT(cb, interesting);
* RETRO_PERFORMANCE_START(cb, interesting);
* interesting_work();
* RETRO_PERFORMANCE_STOP(cb, interesting);
*
* RETRO_PERFORMANCE_INIT(cb, maybe_slow);
* RETRO_PERFORMANCE_START(cb, maybe_slow);
* more_interesting_work();
* RETRO_PERFORMANCE_STOP(cb, maybe_slow);
* }
*
* void retro_deinit(void)
* {
* // Asks the frontend to log the results of all performance counters.
* perf_cb.perf_log();
* }
* @endcode
*
* All functions are set by the frontend.
*
* @see RETRO_ENVIRONMENT_GET_PERF_INTERFACE
*/
struct retro_perf_callback
{
/** @copydoc retro_perf_get_time_usec_t */
retro_perf_get_time_usec_t get_time_usec;
/** @copydoc retro_perf_get_counter_t */
retro_get_cpu_features_t get_cpu_features;
/** @copydoc retro_perf_get_counter_t */
retro_perf_get_counter_t get_perf_counter;
/** @copydoc retro_perf_register_t */
retro_perf_register_t perf_register;
/** @copydoc retro_perf_start_t */
retro_perf_start_t perf_start;
/** @copydoc retro_perf_stop_t */
retro_perf_stop_t perf_stop;
/** @copydoc retro_perf_log_t */
retro_perf_log_t perf_log;
};
/** @} */
/**
* @defgroup RETRO_SENSOR Sensor Interface
* @{
*/
/**
* Defines actions that can be performed on sensors.
* @note Cores should only enable sensors while they're actively being used;
* depending on the frontend and platform,
* enabling these sensors may impact battery life.
*
* @see RETRO_ENVIRONMENT_GET_SENSOR_INTERFACE
* @see retro_sensor_interface
* @see retro_set_sensor_state_t
*/
enum retro_sensor_action
{
/** Enables accelerometer input, if one exists. */
RETRO_SENSOR_ACCELEROMETER_ENABLE = 0,
/** Disables accelerometer input, if one exists. */
RETRO_SENSOR_ACCELEROMETER_DISABLE,
/** Enables gyroscope input, if one exists. */
RETRO_SENSOR_GYROSCOPE_ENABLE,
/** Disables gyroscope input, if one exists. */
RETRO_SENSOR_GYROSCOPE_DISABLE,
/** Enables ambient light input, if a luminance sensor exists. */
RETRO_SENSOR_ILLUMINANCE_ENABLE,
/** Disables ambient light input, if a luminance sensor exists. */
RETRO_SENSOR_ILLUMINANCE_DISABLE,
/** @private Defined to ensure <tt>sizeof(enum retro_sensor_action) == sizeof(int)</tt>. Do not use. */
RETRO_SENSOR_DUMMY = INT_MAX
};
/** @defgroup RETRO_SENSOR_ID Sensor Value IDs
* @{
*/
/* Id values for SENSOR types. */
/**
* Returns the device's acceleration along its local X axis minus the effect of gravity, in m/s^2.
*
* Positive values mean that the device is accelerating to the right.
* assuming the user is looking at it head-on.
*/
#define RETRO_SENSOR_ACCELEROMETER_X 0
/**
* Returns the device's acceleration along its local Y axis minus the effect of gravity, in m/s^2.
*
* Positive values mean that the device is accelerating upwards,
* assuming the user is looking at it head-on.
*/
#define RETRO_SENSOR_ACCELEROMETER_Y 1
/**
* Returns the the device's acceleration along its local Z axis minus the effect of gravity, in m/s^2.
*
* Positive values indicate forward acceleration towards the user,
* assuming the user is looking at the device head-on.
*/
#define RETRO_SENSOR_ACCELEROMETER_Z 2
/**
* Returns the angular velocity of the device around its local X axis, in radians per second.
*
* Positive values indicate counter-clockwise rotation.
*
* @note A radian is about 57 degrees, and a full 360-degree rotation is 2*pi radians.
* @see https://developer.android.com/reference/android/hardware/SensorEvent#sensor.type_gyroscope
* for guidance on using this value to derive a device's orientation.
*/
#define RETRO_SENSOR_GYROSCOPE_X 3
/**
* Returns the angular velocity of the device around its local Z axis, in radians per second.
*
* Positive values indicate counter-clockwise rotation.
*
* @note A radian is about 57 degrees, and a full 360-degree rotation is 2*pi radians.
* @see https://developer.android.com/reference/android/hardware/SensorEvent#sensor.type_gyroscope
* for guidance on using this value to derive a device's orientation.
*/
#define RETRO_SENSOR_GYROSCOPE_Y 4
/**
* Returns the angular velocity of the device around its local Z axis, in radians per second.
*
* Positive values indicate counter-clockwise rotation.
*
* @note A radian is about 57 degrees, and a full 360-degree rotation is 2*pi radians.
* @see https://developer.android.com/reference/android/hardware/SensorEvent#sensor.type_gyroscope
* for guidance on using this value to derive a device's orientation.
*/
#define RETRO_SENSOR_GYROSCOPE_Z 5
/**
* Returns the ambient illuminance (light intensity) of the device's environment, in lux.
*
* @see https://en.wikipedia.org/wiki/Lux for a table of common lux values.
*/
#define RETRO_SENSOR_ILLUMINANCE 6
/** @} */
/**
* Adjusts the state of a sensor.
*
* @param port The device port of the controller that owns the sensor given in \c action.
* @param action The action to perform on the sensor.
* Different devices support different sensors.
* @param rate The rate at which the underlying sensor should be updated, in Hz.
* This should be treated as a hint,
* as some device sensors may not support the requested rate
* (if it's configurable at all).
* @returns \c true if the sensor state was successfully adjusted, \c false otherwise.
* @note If one of the \c RETRO_SENSOR_*_ENABLE actions fails,
* this likely means that the given sensor is not available
* on the provided \c port.
* @see retro_sensor_action
*/
typedef bool (RETRO_CALLCONV *retro_set_sensor_state_t)(unsigned port,
enum retro_sensor_action action, unsigned rate);
/**
* Retrieves the current value reported by sensor.
* @param port The device port of the controller that owns the sensor given in \c id.
* @param id The sensor value to query.
* @returns The current sensor value.
* Exact semantics depend on the value given in \c id,
* but will return 0 for invalid arguments.
*
* @see RETRO_SENSOR_ID
*/
typedef float (RETRO_CALLCONV *retro_sensor_get_input_t)(unsigned port, unsigned id);
/**
* An interface that cores can use to access device sensors.
*
* All function pointers are set by the frontend.
*/
struct retro_sensor_interface
{
/** @copydoc retro_set_sensor_state_t */
retro_set_sensor_state_t set_sensor_state;
/** @copydoc retro_sensor_get_input_t */
retro_sensor_get_input_t get_sensor_input;
};
/** @} */
/** @defgroup GET_CAMERA_INTERFACE Camera Interface
* @{
*/
/**
* Denotes the type of buffer in which the camera will store its input.
*
* Different camera drivers may support different buffer types.
*
* @see RETRO_ENVIRONMENT_GET_CAMERA_INTERFACE
* @see retro_camera_callback
*/
enum retro_camera_buffer
{
/**
* Indicates that camera frames should be delivered to the core as an OpenGL texture.
*
* Requires that the core is using an OpenGL context via \c RETRO_ENVIRONMENT_SET_HW_RENDER.
*
* @see retro_camera_frame_opengl_texture_t
*/
RETRO_CAMERA_BUFFER_OPENGL_TEXTURE = 0,
/**
* Indicates that camera frames should be delivered to the core as a raw buffer in memory.
*
* @see retro_camera_frame_raw_framebuffer_t
*/
RETRO_CAMERA_BUFFER_RAW_FRAMEBUFFER,
/**
* @private Defined to ensure <tt>sizeof(enum retro_camera_buffer) == sizeof(int)</tt>.
* Do not use.
*/
RETRO_CAMERA_BUFFER_DUMMY = INT_MAX
};
/**
* Starts an initialized camera.
* The camera is disabled by default,
* and must be enabled with this function before being used.
*
* Set by the frontend.
*
* @returns \c true if the camera was successfully started, \c false otherwise.
* Failure may occur if no actual camera is available,
* or if the frontend doesn't have permission to access it.
* @note Must be called in \c retro_run().
* @see retro_camera_callback
*/
typedef bool (RETRO_CALLCONV *retro_camera_start_t)(void);
/**
* Stops the running camera.
*
* Set by the frontend.
*
* @note Must be called in \c retro_run().
* @warning The frontend may close the camera on its own when unloading the core,
* but this behavior is not guaranteed.
* Cores should clean up the camera before exiting.
* @see retro_camera_callback
*/
typedef void (RETRO_CALLCONV *retro_camera_stop_t)(void);
/**
* Called by the frontend to report the state of the camera driver.
*
* @see retro_camera_callback
*/
typedef void (RETRO_CALLCONV *retro_camera_lifetime_status_t)(void);
/**
* Called by the frontend to report a new camera frame,
* delivered as a raw buffer in memory.
*
* Set by the core.
*
* @param buffer Pointer to the camera's most recent video frame.
* Each pixel is in XRGB8888 format.
* The first pixel represents the top-left corner of the image
* (i.e. the Y axis goes downward).
* @param width The width of the frame given in \c buffer, in pixels.
* @param height The height of the frame given in \c buffer, in pixels.
* @param pitch The width of the frame given in \c buffer, in bytes.
* @warning \c buffer may be invalidated when this function returns,
* so the core should make its own copy of \c buffer if necessary.
* @see RETRO_CAMERA_BUFFER_RAW_FRAMEBUFFER
*/
typedef void (RETRO_CALLCONV *retro_camera_frame_raw_framebuffer_t)(const uint32_t *buffer,
unsigned width, unsigned height, size_t pitch);
/**
* Called by the frontend to report a new camera frame,
* delivered as an OpenGL texture.
*
* @param texture_id The ID of the OpenGL texture that represents the camera's most recent frame.
* Owned by the frontend, and must not be modified by the core.
* @param texture_target The type of the texture given in \c texture_id.
* Usually either \c GL_TEXTURE_2D or \c GL_TEXTURE_RECTANGLE,
* but other types are allowed.
* @param affine A pointer to a 3x3 column-major affine matrix
* that can be used to transform pixel coordinates to texture coordinates.
* After transformation, the bottom-left corner should have coordinates of <tt>(0, 0)</tt>
* and the top-right corner should have coordinates of <tt>(1, 1)</tt>
* (or <tt>(width, height)</tt> for \c GL_TEXTURE_RECTANGLE).
*
* @note GL-specific typedefs (e.g. \c GLfloat and \c GLuint) are avoided here
* so that the API doesn't rely on gl.h.
* @warning \c texture_id and \c affine may be invalidated when this function returns,
* so the core should make its own copy of them if necessary.
*/
typedef void (RETRO_CALLCONV *retro_camera_frame_opengl_texture_t)(unsigned texture_id,
unsigned texture_target, const float *affine);
/**
* An interface that the core can use to access a device's camera.
*
* @see RETRO_ENVIRONMENT_GET_CAMERA_INTERFACE
*/
struct retro_camera_callback
{
/**
* Requested camera capabilities,
* given as a bitmask of \c retro_camera_buffer values.
* Set by the core.
*
* Here's a usage example:
* @code
* // Requesting support for camera data delivered as both an OpenGL texture and a pixel buffer:
* struct retro_camera_callback callback;
* callback.caps = (1 << RETRO_CAMERA_BUFFER_OPENGL_TEXTURE) | (1 << RETRO_CAMERA_BUFFER_RAW_FRAMEBUFFER);
* @endcode
*/
uint64_t caps;
/**
* The desired width of the camera frame, in pixels.
* This is only a hint; the frontend may provide a different size.
* Set by the core.
* Use zero to let the frontend decide.
*/
unsigned width;
/**
* The desired height of the camera frame, in pixels.
* This is only a hint; the frontend may provide a different size.
* Set by the core.
* Use zero to let the frontend decide.
*/
unsigned height;
/**
* @copydoc retro_camera_start_t
* @see retro_camera_callback
*/
retro_camera_start_t start;
/**
* @copydoc retro_camera_stop_t
* @see retro_camera_callback
*/
retro_camera_stop_t stop;
/**
* @copydoc retro_camera_frame_raw_framebuffer_t
* @note If \c NULL, this function will not be called.
*/
retro_camera_frame_raw_framebuffer_t frame_raw_framebuffer;
/**
* @copydoc retro_camera_frame_opengl_texture_t
* @note If \c NULL, this function will not be called.
*/
retro_camera_frame_opengl_texture_t frame_opengl_texture;
/**
* Core-defined callback invoked by the frontend right after the camera driver is initialized
* (\em not when calling \c start).
* May be \c NULL, in which case this function is skipped.
*/
retro_camera_lifetime_status_t initialized;
/**
* Core-defined callback invoked by the frontend
* right before the video camera driver is deinitialized
* (\em not when calling \c stop).
* May be \c NULL, in which case this function is skipped.
*/
retro_camera_lifetime_status_t deinitialized;
};
/** @} */
/** @defgroup GET_LOCATION_INTERFACE Location Interface
* @{
*/
/** @copydoc retro_location_callback::set_interval */
typedef void (RETRO_CALLCONV *retro_location_set_interval_t)(unsigned interval_ms,
unsigned interval_distance);
/** @copydoc retro_location_callback::start */
typedef bool (RETRO_CALLCONV *retro_location_start_t)(void);
/** @copydoc retro_location_callback::stop */
typedef void (RETRO_CALLCONV *retro_location_stop_t)(void);
/** @copydoc retro_location_callback::get_position */
typedef bool (RETRO_CALLCONV *retro_location_get_position_t)(double *lat, double *lon,
double *horiz_accuracy, double *vert_accuracy);
/** Function type that reports the status of the location service. */
typedef void (RETRO_CALLCONV *retro_location_lifetime_status_t)(void);
/**
* An interface that the core can use to access a device's location.
*
* @note It is the frontend's responsibility to request the necessary permissions
* from the operating system.
* @see RETRO_ENVIRONMENT_GET_LOCATION_INTERFACE
*/
struct retro_location_callback
{
/**
* Starts listening the device's location service.
*
* The frontend will report changes to the device's location
* at the interval defined by \c set_interval.
* Set by the frontend.
*
* @return true if location services were successfully started, false otherwise.
* Note that this will return \c false if location services are disabled
* or the frontend doesn't have permission to use them.
* @note The device's location service may or may not have been enabled
* before the core calls this function.
*/
retro_location_start_t start;
/**
* Stop listening to the device's location service.
*
* Set by the frontend.
*
* @note The location service itself may or may not
* be turned off by this function,
* depending on the platform and the frontend.
* @post The core will stop receiving location service updates.
*/
retro_location_stop_t stop;
/**
* Returns the device's current coordinates.
*
* Set by the frontend.
*
* @param[out] lat Pointer to latitude, in degrees.
* Will be set to 0 if no change has occurred since the last call.
* Behavior is undefined if \c NULL.
* @param[out] lon Pointer to longitude, in degrees.
* Will be set to 0 if no change has occurred since the last call.
* Behavior is undefined if \c NULL.
* @param[out] horiz_accuracy Pointer to horizontal accuracy.
* Will be set to 0 if no change has occurred since the last call.
* Behavior is undefined if \c NULL.
* @param[out] vert_accuracy Pointer to vertical accuracy.
* Will be set to 0 if no change has occurred since the last call.
* Behavior is undefined if \c NULL.
*/
retro_location_get_position_t get_position;
/**
* Sets the rate at which the location service should report updates.
*
* This is only a hint; the actual rate may differ.
* Sets the interval of time and/or distance at which to update/poll
* location-based data.
*
* Some platforms may only support one of the two parameters;
* cores should provide both to ensure compatibility.
*
* Set by the frontend.
*
* @param interval_ms The desired period of time between location updates, in milliseconds.
* @param interval_distance The desired distance between location updates, in meters.
*/
retro_location_set_interval_t set_interval;
/** Called when the location service is initialized. Set by the core. Optional. */
retro_location_lifetime_status_t initialized;
/** Called when the location service is deinitialized. Set by the core. Optional. */
retro_location_lifetime_status_t deinitialized;
};
/** @} */
/** @addtogroup GET_RUMBLE_INTERFACE
* @{ */
/**
* The type of rumble motor in a controller.
*
* Both motors can be controlled independently,
* and the strong motor does not override the weak motor.
* @see RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE
*/
enum retro_rumble_effect
{
RETRO_RUMBLE_STRONG = 0,
RETRO_RUMBLE_WEAK = 1,
/** @private Defined to ensure <tt>sizeof(enum retro_rumble_effect) == sizeof(int)</tt>. Do not use. */
RETRO_RUMBLE_DUMMY = INT_MAX
};
/**
* Requests a rumble state change for a controller.
* Set by the frontend.
*
* @param port The controller port to set the rumble state for.
* @param effect The rumble motor to set the strength of.
* @param strength The desired intensity of the rumble motor, ranging from \c 0 to \c 0xffff (inclusive).
* @return \c true if the requested rumble state was honored.
* If the controller doesn't support rumble, will return \c false.
* @note Calling this before the first \c retro_run() may return \c false.
* @see RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE
*/
typedef bool (RETRO_CALLCONV *retro_set_rumble_state_t)(unsigned port,
enum retro_rumble_effect effect, uint16_t strength);
/**
* An interface that the core can use to set the rumble state of a controller.
* @see RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE
*/
struct retro_rumble_interface
{
/** @copydoc retro_set_rumble_state_t */
retro_set_rumble_state_t set_rumble_state;
};
/** @} */
/**
* Called by the frontend to request audio samples.
* The core should render audio within this function
* using the callback provided by \c retro_set_audio_sample or \c retro_set_audio_sample_batch.
*
* @warning This function may be called by any thread,
* therefore it must be thread-safe.
* @see RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK
* @see retro_audio_callback
* @see retro_audio_sample_batch_t
* @see retro_audio_sample_t
*/
typedef void (RETRO_CALLCONV *retro_audio_callback_t)(void);
/**
* Called by the frontend to notify the core that it should pause or resume audio rendering.
* The initial state of the audio driver after registering this callback is \c false (inactive).
*
* @param enabled \c true if the frontend's audio driver is active.
* If so, the registered audio callback will be called regularly.
* If not, the audio callback will not be invoked until the next time
* the frontend calls this function with \c true.
* @warning This function may be called by any thread,
* therefore it must be thread-safe.
* @note Even if no audio samples are rendered,
* the core should continue to update its emulated platform's audio engine if necessary.
* @see RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK
* @see retro_audio_callback
* @see retro_audio_callback_t
*/
typedef void (RETRO_CALLCONV *retro_audio_set_state_callback_t)(bool enabled);
/**
* An interface that the frontend uses to request audio samples from the core.
* @note To unregister a callback, pass a \c retro_audio_callback_t
* with both fields set to <tt>NULL</tt>.
* @see RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK
*/
struct retro_audio_callback
{
/** @see retro_audio_callback_t */
retro_audio_callback_t callback;
/** @see retro_audio_set_state_callback_t */
retro_audio_set_state_callback_t set_state;
};
typedef int64_t retro_usec_t;
/**
* Called right before each iteration of \c retro_run
* if registered via <tt>RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK</tt>.
*
* @param usec Time since the last call to <tt>retro_run</tt>, in microseconds.
* If the frontend is manipulating the frame time
* (e.g. via fast-forward or slow motion),
* this value will be the reference value initially provided to the environment call.
* @see RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK
* @see retro_frame_time_callback
*/
typedef void (RETRO_CALLCONV *retro_frame_time_callback_t)(retro_usec_t usec);
/**
* @see RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK
*/
struct retro_frame_time_callback
{
/**
* Called to notify the core of the current frame time.
* If <tt>NULL</tt>, the frontend will clear its registered callback.
*/
retro_frame_time_callback_t callback;
/**
* The ideal duration of one frame, in microseconds.
* Compute it as <tt>1000000 / fps</tt>.
* The frontend will resolve rounding to ensure that framestepping, etc is exact.
*/
retro_usec_t reference;
};
/** @defgroup SET_AUDIO_BUFFER_STATUS_CALLBACK Audio Buffer Occupancy
* @{
*/
/**
* Notifies a libretro core of how full the frontend's audio buffer is.
* Set by the core, called by the frontend.
* It will be called right before \c retro_run() every frame.
*
* @param active \c true if the frontend's audio buffer is currently in use,
* \c false if audio is disabled in the frontend.
* @param occupancy A value between 0 and 100 (inclusive),
* corresponding to the frontend's audio buffer occupancy percentage.
* @param underrun_likely \c true if the frontend expects an audio buffer underrun
* during the next frame, which indicates that a core should attempt frame-skipping.
*/
typedef void (RETRO_CALLCONV *retro_audio_buffer_status_callback_t)(
bool active, unsigned occupancy, bool underrun_likely);
/**
* A callback to register with the frontend to receive audio buffer occupancy information.
*/
struct retro_audio_buffer_status_callback
{
/** @copydoc retro_audio_buffer_status_callback_t */
retro_audio_buffer_status_callback_t callback;
};
/** @} */
/* Pass this to retro_video_refresh_t if rendering to hardware.
* Passing NULL to retro_video_refresh_t is still a frame dupe as normal.
* */
#define RETRO_HW_FRAME_BUFFER_VALID ((void*)-1)
/* Invalidates the current HW context.
* Any GL state is lost, and must not be deinitialized explicitly.
* If explicit deinitialization is desired by the libretro core,
* it should implement context_destroy callback.
* If called, all GPU resources must be reinitialized.
* Usually called when frontend reinits video driver.
* Also called first time video driver is initialized,
* allowing libretro core to initialize resources.
*/
typedef void (RETRO_CALLCONV *retro_hw_context_reset_t)(void);
/* Gets current framebuffer which is to be rendered to.
* Could change every frame potentially.
*/
typedef uintptr_t (RETRO_CALLCONV *retro_hw_get_current_framebuffer_t)(void);
/* Get a symbol from HW context. */
typedef retro_proc_address_t (RETRO_CALLCONV *retro_hw_get_proc_address_t)(const char *sym);
enum retro_hw_context_type
{
RETRO_HW_CONTEXT_NONE = 0,
/* OpenGL 2.x. Driver can choose to use latest compatibility context. */
RETRO_HW_CONTEXT_OPENGL = 1,
/* OpenGL ES 2.0. */
RETRO_HW_CONTEXT_OPENGLES2 = 2,
/* Modern desktop core GL context. Use version_major/
* version_minor fields to set GL version. */
RETRO_HW_CONTEXT_OPENGL_CORE = 3,
/* OpenGL ES 3.0 */
RETRO_HW_CONTEXT_OPENGLES3 = 4,
/* OpenGL ES 3.1+. Set version_major/version_minor. For GLES2 and GLES3,
* use the corresponding enums directly. */
RETRO_HW_CONTEXT_OPENGLES_VERSION = 5,
/* Vulkan, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE. */
RETRO_HW_CONTEXT_VULKAN = 6,
/* Direct3D11, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */
RETRO_HW_CONTEXT_D3D11 = 7,
/* Direct3D10, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */
RETRO_HW_CONTEXT_D3D10 = 8,
/* Direct3D12, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */
RETRO_HW_CONTEXT_D3D12 = 9,
/* Direct3D9, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */
RETRO_HW_CONTEXT_D3D9 = 10,
/** Dummy value to ensure sizeof(enum retro_hw_context_type) == sizeof(int). Do not use. */
RETRO_HW_CONTEXT_DUMMY = INT_MAX
};
struct retro_hw_render_callback
{
/* Which API to use. Set by libretro core. */
enum retro_hw_context_type context_type;
/* Called when a context has been created or when it has been reset.
* An OpenGL context is only valid after context_reset() has been called.
*
* When context_reset is called, OpenGL resources in the libretro
* implementation are guaranteed to be invalid.
*
* It is possible that context_reset is called multiple times during an
* application lifecycle.
* If context_reset is called without any notification (context_destroy),
* the OpenGL context was lost and resources should just be recreated
* without any attempt to "free" old resources.
*/
retro_hw_context_reset_t context_reset;
/* Set by frontend.
* TODO: This is rather obsolete. The frontend should not
* be providing preallocated framebuffers. */
retro_hw_get_current_framebuffer_t get_current_framebuffer;
/* Set by frontend.
* Can return all relevant functions, including glClear on Windows. */
retro_hw_get_proc_address_t get_proc_address;
/* Set if render buffers should have depth component attached.
* TODO: Obsolete. */
bool depth;
/* Set if stencil buffers should be attached.
* TODO: Obsolete. */
bool stencil;
/* If depth and stencil are true, a packed 24/8 buffer will be added.
* Only attaching stencil is invalid and will be ignored. */
/* Use conventional bottom-left origin convention. If false,
* standard libretro top-left origin semantics are used.
* TODO: Move to GL specific interface. */
bool bottom_left_origin;
/* Major version number for core GL context or GLES 3.1+. */
unsigned version_major;
/* Minor version number for core GL context or GLES 3.1+. */
unsigned version_minor;
/* If this is true, the frontend will go very far to avoid
* resetting context in scenarios like toggling fullscreen, etc.
* TODO: Obsolete? Maybe frontend should just always assume this ...
*/
bool cache_context;
/* The reset callback might still be called in extreme situations
* such as if the context is lost beyond recovery.
*
* For optimal stability, set this to false, and allow context to be
* reset at any time.
*/
/* A callback to be called before the context is destroyed in a
* controlled way by the frontend. */
retro_hw_context_reset_t context_destroy;
/* OpenGL resources can be deinitialized cleanly at this step.
* context_destroy can be set to NULL, in which resources will
* just be destroyed without any notification.
*
* Even when context_destroy is non-NULL, it is possible that
* context_reset is called without any destroy notification.
* This happens if context is lost by external factors (such as
* notified by GL_ARB_robustness).
*
* In this case, the context is assumed to be already dead,
* and the libretro implementation must not try to free any OpenGL
* resources in the subsequent context_reset.
*/
/* Creates a debug context. */
bool debug_context;
};
/* Callback type passed in RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK.
* Called by the frontend in response to keyboard events.
* down is set if the key is being pressed, or false if it is being released.
* keycode is the RETROK value of the char.
* character is the text character of the pressed key. (UTF-32).
* key_modifiers is a set of RETROKMOD values or'ed together.
*
* The pressed/keycode state can be indepedent of the character.
* It is also possible that multiple characters are generated from a
* single keypress.
* Keycode events should be treated separately from character events.
* However, when possible, the frontend should try to synchronize these.
* If only a character is posted, keycode should be RETROK_UNKNOWN.
*
* Similarily if only a keycode event is generated with no corresponding
* character, character should be 0.
*/
typedef void (RETRO_CALLCONV *retro_keyboard_event_t)(bool down, unsigned keycode,
uint32_t character, uint16_t key_modifiers);
struct retro_keyboard_callback
{
retro_keyboard_event_t callback;
};
/** @defgroup SET_DISK_CONTROL_INTERFACE Disk Control
*
* Callbacks for inserting and removing disks from the emulated console at runtime.
* Should be provided by cores that support doing so.
* Cores should automate this process if possible,
* but some cases require the player's manual input.
*
* The steps for swapping disk images are generally as follows:
*
* \li Eject the emulated console's disk drive with \c set_eject_state(true).
* \li Insert the new disk image with \c set_image_index(index).
* \li Close the virtual disk tray with \c set_eject_state(false).
*
* @{
*/
/**
* Called by the frontend to open or close the emulated console's virtual disk tray.
*
* The frontend may only set the disk image index
* while the emulated tray is opened.
*
* If the emulated console's disk tray is already in the state given by \c ejected,
* then this function should return \c true without doing anything.
* The core should return \c false if it couldn't change the disk tray's state;
* this may happen if the console itself limits when the disk tray can be open or closed
* (e.g. to wait for the disc to stop spinning).
*
* @param ejected \c true if the virtual disk tray should be "ejected",
* \c false if it should be "closed".
* @return \c true if the virtual disk tray's state has been set to the given state,
* false if there was an error.
* @see retro_get_eject_state_t
*/
typedef bool (RETRO_CALLCONV *retro_set_eject_state_t)(bool ejected);
/**
* Gets the current ejected state of the disk drive.
* The initial state is closed, i.e. \c false.
*
* @return \c true if the virtual disk tray is "ejected",
* i.e. it's open and a disk can be inserted.
* @see retro_set_eject_state_t
*/
typedef bool (RETRO_CALLCONV *retro_get_eject_state_t)(void);
/**
* Gets the index of the current disk image,
* as determined by however the frontend orders disk images
* (such as m3u-formatted playlists or special directories).
*
* @return The index of the current disk image
* (starting with 0 for the first disk),
* or a value greater than or equal to \c get_num_images() if no disk is inserted.
* @see retro_get_num_images_t
*/
typedef unsigned (RETRO_CALLCONV *retro_get_image_index_t)(void);
/**
* Inserts the disk image at the given index into the emulated console's drive.
* Can only be called while the disk tray is ejected
* (i.e. \c retro_get_eject_state_t returns \c true).
*
* If the emulated disk tray is ejected
* and already contains the disk image named by \c index,
* then this function should do nothing and return \c true.
*
* @param index The index of the disk image to insert,
* starting from 0 for the first disk.
* A value greater than or equal to \c get_num_images()
* represents the frontend removing the disk without inserting a new one.
* @return \c true if the disk image was successfully set.
* \c false if the disk tray isn't ejected or there was another error
* inserting a new disk image.
*/
typedef bool (RETRO_CALLCONV *retro_set_image_index_t)(unsigned index);
/**
* @return The number of disk images which are available to use.
* These are most likely defined in a playlist file.
*/
typedef unsigned (RETRO_CALLCONV *retro_get_num_images_t)(void);
struct retro_game_info;
/**
* Replaces the disk image at the given index with a new disk.
*
* Replaces the disk image associated with index.
* Arguments to pass in info have same requirements as retro_load_game().
* Virtual disk tray must be ejected when calling this.
*
* Passing \c NULL to this function indicates
* that the frontend has removed this disk image from its internal list.
* As a result, calls to this function can change the number of available disk indexes.
*
* For example, calling <tt>replace_image_index(1, NULL)</tt>
* will remove the disk image at index 1,
* and the disk image at index 2 (if any)
* will be moved to the newly-available index 1.
*
* @param index The index of the disk image to replace.
* @param info Details about the new disk image,
* or \c NULL if the disk image at the given index should be discarded.
* The semantics of each field are the same as in \c retro_load_game.
* @return \c true if the disk image was successfully replaced
* or removed from the playlist,
* \c false if the tray is not ejected
* or if there was an error.
*/
typedef bool (RETRO_CALLCONV *retro_replace_image_index_t)(unsigned index,
const struct retro_game_info *info);
/**
* Adds a new index to the core's internal disk list.
* This will increment the return value from \c get_num_images() by 1.
* This image index cannot be used until a disk image has been set
* with \c replace_image_index.
*
* @return \c true if the core has added space for a new disk image
* and is ready to receive one.
*/
typedef bool (RETRO_CALLCONV *retro_add_image_index_t)(void);
/**
* Sets the disk image that will be inserted into the emulated disk drive
* before \c retro_load_game is called.
*
* \c retro_load_game does not provide a way to ensure
* that a particular disk image in a playlist is inserted into the console;
* this function makes up for that.
* Frontends should call it immediately before \c retro_load_game,
* and the core should use the arguments
* to validate the disk image in \c retro_load_game.
*
* When content is loaded, the core should verify that the
* disk specified by \c index can be found at \c path.
* This is to guard against auto-selecting the wrong image
* if (for example) the user should modify an existing M3U playlist.
* We have to let the core handle this because
* \c set_initial_image() must be called before loading content,
* i.e. the frontend cannot access image paths in advance
* and thus cannot perform the error check itself.
* If \c index is invalid (i.e. <tt>index >= get_num_images()</tt>)
* or the disk image doesn't match the value given in \c path,
* the core should ignore the arguments
* and insert the disk at index 0 into the virtual disk tray.
*
* @warning If \c RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE is called within \c retro_load_game,
* then this function may not be executed.
* Set the disk control interface in \c retro_init if possible.
*
* @param index The index of the disk image within the playlist to set.
* @param path The path of the disk image to set as the first.
* The core should not load this path immediately;
* instead, it should use it within \c retro_load_game
* to verify that the correct disk image was loaded.
* @return \c true if the initial disk index was set,
* \c false if the arguments are invalid
* or the core doesn't support this function.
*/
typedef bool (RETRO_CALLCONV *retro_set_initial_image_t)(unsigned index, const char *path);
/**
* Returns the path of the disk image at the given index
* on the host's file system.
*
* @param index The index of the disk image to get the path of.
* @param path A buffer to store the path in.
* @param len The size of \c path, in bytes.
* @return \c true if the disk image's location was successfully
* queried and copied into \c path,
* \c false if the index is invalid
* or the core couldn't locate the disk image.
*/
typedef bool (RETRO_CALLCONV *retro_get_image_path_t)(unsigned index, char *path, size_t len);
/**
* Returns a friendly label for the given disk image.
*
* In the simplest case, this may be the disk image's file name
* with the extension omitted.
* For cores or games with more complex content requirements,
* the label can be used to provide information to help the player
* select a disk image to insert;
* for example, a core may label different kinds of disks
* (save data, level disk, installation disk, bonus content, etc.).
* with names that correspond to in-game prompts,
* so that the frontend can provide better guidance to the player.
*
* @param index The index of the disk image to return a label for.
* @param label A buffer to store the resulting label in.
* @param len The length of \c label, in bytes.
* @return \c true if the disk image at \c index is valid
* and a label was copied into \c label.
*/
typedef bool (RETRO_CALLCONV *retro_get_image_label_t)(unsigned index, char *label, size_t len);
/**
* An interface that the frontend can use to exchange disks
* within the emulated console's disk drive.
*
* All function pointers are required.
*
* @deprecated This struct is superseded by \ref retro_disk_control_ext_callback.
* Only use this one to maintain compatibility
* with older cores and frontends.
*
* @see RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE
* @see retro_disk_control_ext_callback
*/
struct retro_disk_control_callback
{
/** @copydoc retro_set_eject_state_t */
retro_set_eject_state_t set_eject_state;
/** @copydoc retro_get_eject_state_t */
retro_get_eject_state_t get_eject_state;
/** @copydoc retro_get_image_index_t */
retro_get_image_index_t get_image_index;
/** @copydoc retro_set_image_index_t */
retro_set_image_index_t set_image_index;
/** @copydoc retro_get_num_images_t */
retro_get_num_images_t get_num_images;
/** @copydoc retro_replace_image_index_t */
retro_replace_image_index_t replace_image_index;
/** @copydoc retro_add_image_index_t */
retro_add_image_index_t add_image_index;
};
/**
* @copybrief retro_disk_control_callback
*
* All function pointers are required unless otherwise noted.
*
* @see RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE
*/
struct retro_disk_control_ext_callback
{
/** @copydoc retro_set_eject_state_t */
retro_set_eject_state_t set_eject_state;
/** @copydoc retro_get_eject_state_t */
retro_get_eject_state_t get_eject_state;
/** @copydoc retro_get_image_index_t */
retro_get_image_index_t get_image_index;
/** @copydoc retro_set_image_index_t */
retro_set_image_index_t set_image_index;
/** @copydoc retro_get_num_images_t */
retro_get_num_images_t get_num_images;
/** @copydoc retro_replace_image_index_t */
retro_replace_image_index_t replace_image_index;
/** @copydoc retro_add_image_index_t */
retro_add_image_index_t add_image_index;
/** @copydoc retro_set_initial_image_t
*
* Optional; not called if \c NULL.
*
* @note The frontend will only try to record/restore the last-used disk index
* if both \c set_initial_image and \c get_image_path are implemented.
*/
retro_set_initial_image_t set_initial_image;
/**
* @copydoc retro_get_image_path_t
*
* Optional; not called if \c NULL.
*/
retro_get_image_path_t get_image_path;
/**
* @copydoc retro_get_image_label_t
*
* Optional; not called if \c NULL.
*/
retro_get_image_label_t get_image_label;
};
/** @} */
/* Definitions for RETRO_ENVIRONMENT_SET_NETPACKET_INTERFACE.
* A core can set it if sending and receiving custom network packets
* during a multiplayer session is desired.
*/
/* Netpacket flags for retro_netpacket_send_t */
#define RETRO_NETPACKET_UNRELIABLE 0 /* Packet to be sent unreliable, depending on network quality it might not arrive. */
#define RETRO_NETPACKET_RELIABLE (1 << 0) /* Reliable packets are guaranteed to arrive at the target in the order they were sent. */
#define RETRO_NETPACKET_UNSEQUENCED (1 << 1) /* Packet will not be sequenced with other packets and may arrive out of order. Cannot be set on reliable packets. */
#define RETRO_NETPACKET_FLUSH_HINT (1 << 2) /* Request the packet and any previously buffered ones to be sent immediately */
/* Broadcast client_id for retro_netpacket_send_t */
#define RETRO_NETPACKET_BROADCAST 0xFFFF
/* Used by the core to send a packet to one or all connected players.
* A single packet sent via this interface can contain up to 64 KB of data.
*
* The client_id RETRO_NETPACKET_BROADCAST sends the packet as a broadcast to
* all connected players. This is supported from the host as well as clients.
* Otherwise, the argument indicates the player to send the packet to.
*
* A frontend must support sending reliable packets (RETRO_NETPACKET_RELIABLE).
* Unreliable packets might not be supported by the frontend, but the flags can
* still be specified. Reliable transmission will be used instead.
*
* Calling this with the flag RETRO_NETPACKET_FLUSH_HINT will send off the
* packet and any previously buffered ones immediately and without blocking.
* To only flush previously queued packets, buf or len can be passed as NULL/0.
*
* This function is not guaranteed to be thread-safe and must be called during
* retro_run or any of the netpacket callbacks passed with this interface.
*/
typedef void (RETRO_CALLCONV *retro_netpacket_send_t)(int flags, const void* buf, size_t len, uint16_t client_id);
/* Optionally read any incoming packets without waiting for the end of the
* frame. While polling, retro_netpacket_receive_t and retro_netpacket_stop_t
* can be called. The core can perform this in a loop to do a blocking read,
* i.e., wait for incoming data, but needs to handle stop getting called and
* also give up after a short while to avoid freezing on a connection problem.
* It is a good idea to manually flush outgoing packets before calling this.
*
* This function is not guaranteed to be thread-safe and must be called during
* retro_run or any of the netpacket callbacks passed with this interface.
*/
typedef void (RETRO_CALLCONV *retro_netpacket_poll_receive_t)(void);
/* Called by the frontend to signify that a multiplayer session has started.
* If client_id is 0 the local player is the host of the session and at this
* point no other player has connected yet.
*
* If client_id is > 0 the local player is a client connected to a host and
* at this point is already fully connected to the host.
*
* The core must store the function pointer send_fn and use it whenever it
* wants to send a packet. Optionally poll_receive_fn can be stored and used
* when regular receiving between frames is not enough. These function pointers
* remain valid until the frontend calls retro_netpacket_stop_t.
*/
typedef void (RETRO_CALLCONV *retro_netpacket_start_t)(uint16_t client_id, retro_netpacket_send_t send_fn, retro_netpacket_poll_receive_t poll_receive_fn);
/* Called by the frontend when a new packet arrives which has been sent from
* another player with retro_netpacket_send_t. The client_id argument indicates
* who has sent the packet.
*/
typedef void (RETRO_CALLCONV *retro_netpacket_receive_t)(const void* buf, size_t len, uint16_t client_id);
/* Called by the frontend when the multiplayer session has ended.
* Once this gets called the function pointers passed to
* retro_netpacket_start_t will not be valid anymore.
*/
typedef void (RETRO_CALLCONV *retro_netpacket_stop_t)(void);
/* Called by the frontend every frame (between calls to retro_run while
* updating the state of the multiplayer session.
* This is a good place for the core to call retro_netpacket_send_t from.
*/
typedef void (RETRO_CALLCONV *retro_netpacket_poll_t)(void);
/* Called by the frontend when a new player connects to the hosted session.
* This is only called on the host side, not for clients connected to the host.
* If this function returns false, the newly connected player gets dropped.
* This can be used for example to limit the number of players.
*/
typedef bool (RETRO_CALLCONV *retro_netpacket_connected_t)(uint16_t client_id);
/* Called by the frontend when a player leaves or disconnects from the hosted session.
* This is only called on the host side, not for clients connected to the host.
*/
typedef void (RETRO_CALLCONV *retro_netpacket_disconnected_t)(uint16_t client_id);
/**
* A callback interface for giving a core the ability to send and receive custom
* network packets during a multiplayer session between two or more instances
* of a libretro frontend.
*
* Normally during connection handshake the frontend will compare library_version
* used by both parties and show a warning if there is a difference. When the core
* supplies protocol_version, the frontend will check against this instead.
*
* @see RETRO_ENVIRONMENT_SET_NETPACKET_INTERFACE
*/
struct retro_netpacket_callback
{
retro_netpacket_start_t start;
retro_netpacket_receive_t receive;
retro_netpacket_stop_t stop; /* Optional - may be NULL */
retro_netpacket_poll_t poll; /* Optional - may be NULL */
retro_netpacket_connected_t connected; /* Optional - may be NULL */
retro_netpacket_disconnected_t disconnected; /* Optional - may be NULL */
const char* protocol_version; /* Optional - if not NULL will be used instead of core version to decide if communication is compatible */
};
/**
* The pixel format used for rendering.
* @see RETRO_ENVIRONMENT_SET_PIXEL_FORMAT
*/
enum retro_pixel_format
{
/**
* 0RGB1555, native endian.
* Used as the default if \c RETRO_ENVIRONMENT_SET_PIXEL_FORMAT is not called.
* The most significant bit must be set to 0.
* @deprecated This format remains supported to maintain compatibility.
* New code should use <tt>RETRO_PIXEL_FORMAT_RGB565</tt> instead.
* @see RETRO_PIXEL_FORMAT_RGB565
*/
RETRO_PIXEL_FORMAT_0RGB1555 = 0,
/**
* XRGB8888, native endian.
* The most significant byte (the <tt>X</tt>) is ignored.
*/
RETRO_PIXEL_FORMAT_XRGB8888 = 1,
/**
* RGB565, native endian.
* This format is recommended if 16-bit pixels are desired,
* as it is available on a variety of devices and APIs.
*/
RETRO_PIXEL_FORMAT_RGB565 = 2,
/** Defined to ensure that <tt>sizeof(retro_pixel_format) == sizeof(int)</tt>. Do not use. */
RETRO_PIXEL_FORMAT_UNKNOWN = INT_MAX
};
/** @defgroup GET_SAVESTATE_CONTEXT Savestate Context
* @{
*/
/**
* Details about how the frontend will use savestates.
*
* @see RETRO_ENVIRONMENT_GET_SAVESTATE_CONTEXT
* @see retro_serialize
*/
enum retro_savestate_context
{
/**
* Standard savestate written to disk.
* May be loaded at any time,
* even in a separate session or on another device.
*
* Should not contain any pointers to code or data.
*/
RETRO_SAVESTATE_CONTEXT_NORMAL = 0,
/**
* The savestate is guaranteed to be loaded
* within the same session, address space, and binary.
* Will not be written to disk or sent over the network;
* therefore, internal pointers to code or data are acceptable.
* May still be loaded or saved at any time.
*
* @note This context generally implies the use of runahead or rewinding,
* which may work by taking savestates multiple times per second.
* Savestate code that runs in this context should be fast.
*/
RETRO_SAVESTATE_CONTEXT_RUNAHEAD_SAME_INSTANCE = 1,
/**
* The savestate is guaranteed to be loaded
* in the same session and by the same binary,
* but possibly by a different address space
* (e.g. for "second instance" runahead)
*
* Will not be written to disk or sent over the network,
* but may be loaded in a different address space.
* Therefore, the savestate <em>must not</em> contain pointers.
*/
RETRO_SAVESTATE_CONTEXT_RUNAHEAD_SAME_BINARY = 2,
/**
* The savestate will not be written to disk,
* but no other guarantees are made.
* The savestate will almost certainly be loaded
* by a separate binary, device, and address space.
*
* This context is intended for use with frontends that support rollback netplay.
* Serialized state should omit any data that would unnecessarily increase bandwidth usage.
* Must not contain pointers, and integers must be saved in big-endian format.
* @see retro_endianness.h
* @see network_stream
*/
RETRO_SAVESTATE_CONTEXT_ROLLBACK_NETPLAY = 3,
/**
* @private Defined to ensure <tt>sizeof(retro_savestate_context) == sizeof(int)</tt>.
* Do not use.
*/
RETRO_SAVESTATE_CONTEXT_UNKNOWN = INT_MAX
};
/** @} */
/** @defgroup SET_MESSAGE User-Visible Messages
*
* @{
*/
/**
* Defines a message that the frontend will display to the user,
* as determined by <tt>RETRO_ENVIRONMENT_SET_MESSAGE</tt>.
*
* @deprecated This struct is superseded by \ref retro_message_ext,
* which provides more control over how a message is presented.
* Only use it for compatibility with older cores and frontends.
*
* @see RETRO_ENVIRONMENT_SET_MESSAGE
* @see retro_message_ext
*/
struct retro_message
{
/**
* Null-terminated message to be displayed.
* If \c NULL or empty, the message will be ignored.
*/
const char *msg;
/** Duration to display \c msg in frames. */
unsigned frames;
};
/**
* The method that the frontend will use to display a message to the player.
* @see retro_message_ext
*/
enum retro_message_target
{
/**
* Indicates that the frontent should display the given message
* using all other targets defined by \c retro_message_target at once.
*/
RETRO_MESSAGE_TARGET_ALL = 0,
/**
* Indicates that the frontend should display the given message
* using the frontend's on-screen display, if available.
*
* @attention If the frontend allows players to customize or disable notifications,
* then they may not see messages sent to this target.
*/
RETRO_MESSAGE_TARGET_OSD,
/**
* Indicates that the frontend should log the message
* via its usual logging mechanism, if available.
*
* This is not intended to be a substitute for \c RETRO_ENVIRONMENT_SET_LOG_INTERFACE.
* It is intended for the common use case of
* logging a player-facing message.
*
* This target should not be used for messages
* of type \c RETRO_MESSAGE_TYPE_STATUS or \c RETRO_MESSAGE_TYPE_PROGRESS,
* as it may add unnecessary noise to a log file.
*
* @see RETRO_ENVIRONMENT_SET_LOG_INTERFACE
*/
RETRO_MESSAGE_TARGET_LOG
};
/**
* A broad category for the type of message that the frontend will display.
*
* Each message type has its own use case,
* therefore the frontend should present each one differently.
*
* @note This is a hint that the frontend may ignore.
* The frontend should fall back to \c RETRO_MESSAGE_TYPE_NOTIFICATION
* for message types that it doesn't support.
*/
enum retro_message_type
{
/**
* A standard on-screen message.
*
* Suitable for a variety of use cases,
* such as messages about errors
* or other important events.
*
* Frontends that display their own messages
* should display this type of core-generated message the same way.
*/
RETRO_MESSAGE_TYPE_NOTIFICATION = 0,
/**
* An on-screen message that should be visually distinct
* from \c RETRO_MESSAGE_TYPE_NOTIFICATION messages.
*
* The exact meaning of "visually distinct" is left to the frontend,
* but this usually implies that the frontend shows the message
* in a way that it doesn't typically use for its own notices.
*/
RETRO_MESSAGE_TYPE_NOTIFICATION_ALT,
/**
* Indicates a frequently-updated status display,
* rather than a standard notification.
* Status messages are intended to be displayed permanently while a core is running
* in a way that doesn't suggest user action is required.
*
* Here are some possible use cases for status messages:
*
* @li An internal framerate counter.
* @li Debugging information.
* Remember to let the player disable it in the core options.
* @li Core-specific state, such as when a microphone is active.
*
* The status message is displayed for the given duration,
* unless another status message of equal or greater priority is shown.
*/
RETRO_MESSAGE_TYPE_STATUS,
/**
* Denotes a message that reports the progress
* of a long-running asynchronous task,
* such as when a core loads large files from disk or the network.
*
* The frontend should display messages of this type as a progress bar
* (or a progress spinner for indefinite tasks),
* where \c retro_message_ext::msg is the progress bar's title
* and \c retro_message_ext::progress sets the progress bar's length.
*
* This message type shouldn't be used for tasks that are expected to complete quickly.
*/
RETRO_MESSAGE_TYPE_PROGRESS
};
/**
* A core-provided message that the frontend will display to the player.
*
* @note The frontend is encouraged store these messages in a queue.
* However, it should not empty the queue of core-submitted messages upon exit;
* if a core exits with an error, it may want to use this API
* to show an error message to the player.
*
* The frontend should maintain its own copy of the submitted message
* and all subobjects, including strings.
*
* @see RETRO_ENVIRONMENT_SET_MESSAGE_EXT
*/
struct retro_message_ext
{
/**
* The \c NULL-terminated text of a message to show to the player.
* Must not be \c NULL.
*
* @note The frontend must honor newlines in this string
* when rendering text to \c RETRO_MESSAGE_TARGET_OSD.
*/
const char *msg;
/**
* The duration that \c msg will be displayed on-screen, in milliseconds.
*
* Ignored for \c RETRO_MESSAGE_TARGET_LOG.
*/
unsigned duration;
/**
* The relative importance of this message
* when targeting \c RETRO_MESSAGE_TARGET_OSD.
* Higher values indicate higher priority.
*
* The frontend should use this to prioritize messages
* when it can't show all active messages at once,
* or to remove messages from its queue if it's full.
*
* The relative display order of messages with the same priority
* is left to the frontend's discretion,
* although we suggest breaking ties
* in favor of the most recently-submitted message.
*
* Frontends may handle deprioritized messages at their discretion;
* such messages may have their \c duration altered,
* be hidden without being delayed,
* or even be discarded entirely.
*
* @note In the reference frontend (RetroArch),
* the same priority values are used for frontend-generated notifications,
* which are typically between 0 and 3 depending upon importance.
*
* Ignored for \c RETRO_MESSAGE_TARGET_LOG.
*/
unsigned priority;
/**
* The severity level of this message.
*
* The frontend may use this to filter or customize messages
* depending on the player's preferences.
* Here are some ideas:
*
* @li Use this to prioritize errors and warnings
* over higher-ranking info and debug messages.
* @li Render warnings or errors with extra visual feedback,
* e.g. with brighter colors or accompanying sound effects.
*
* @see RETRO_ENVIRONMENT_SET_LOG_INTERFACE
*/
enum retro_log_level level;
/**
* The intended destination of this message.
*
* @see retro_message_target
*/
enum retro_message_target target;
/**
* The intended semantics of this message.
*
* Ignored for \c RETRO_MESSAGE_TARGET_LOG.
*
* @see retro_message_type
*/
enum retro_message_type type;
/**
* The progress of an asynchronous task.
*
* A value betwen 0 and 100 (inclusive) indicates the task's percentage,
* and a value of -1 indicates a task of unknown completion.
*
* @note Since message type is a hint, a frontend may ignore progress values.
* Where relevant, a core should include progress percentage within the message string,
* such that the message intent remains clear when displayed
* as a standard frontend-generated notification.
*
* Ignored for \c RETRO_MESSAGE_TARGET_LOG and for
* message types other than \c RETRO_MESSAGE_TYPE_PROGRESS.
*/
int8_t progress;
};
/** @} */
/* Describes how the libretro implementation maps a libretro input bind
* to its internal input system through a human readable string.
* This string can be used to better let a user configure input. */
struct retro_input_descriptor
{
/* Associates given parameters with a description. */
unsigned port;
unsigned device;
unsigned index;
unsigned id;
/* Human readable description for parameters.
* The pointer must remain valid until
* retro_unload_game() is called. */
const char *description;
};
/**
* Contains basic information about the core.
*
* @see retro_get_system_info
* @warning All pointers are owned by the core
* and must remain valid throughout its lifetime.
*/
struct retro_system_info
{
/**
* Descriptive name of the library.
*
* @note Should not contain any version numbers, etc.
*/
const char *library_name;
/**
* Descriptive version of the core.
*/
const char *library_version;
/**
* A pipe-delimited string list of file extensions that this core can load, e.g. "bin|rom|iso".
* Typically used by a frontend for filtering or core selection.
*/
const char *valid_extensions;
/* Libretro cores that need to have direct access to their content
* files, including cores which use the path of the content files to
* determine the paths of other files, should set need_fullpath to true.
*
* Cores should strive for setting need_fullpath to false,
* as it allows the frontend to perform patching, etc.
*
* If need_fullpath is true and retro_load_game() is called:
* - retro_game_info::path is guaranteed to have a valid path
* - retro_game_info::data and retro_game_info::size are invalid
*
* If need_fullpath is false and retro_load_game() is called:
* - retro_game_info::path may be NULL
* - retro_game_info::data and retro_game_info::size are guaranteed
* to be valid
*
* See also:
* - RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY
* - RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY
*/
bool need_fullpath;
/* If true, the frontend is not allowed to extract any archives before
* loading the real content.
* Necessary for certain libretro implementations that load games
* from zipped archives. */
bool block_extract;
};
/* Defines overrides which modify frontend handling of
* specific content file types.
* An array of retro_system_content_info_override is
* passed to RETRO_ENVIRONMENT_SET_CONTENT_INFO_OVERRIDE
* NOTE: In the following descriptions, references to
* retro_load_game() may be replaced with
* retro_load_game_special() */
struct retro_system_content_info_override
{
/* A list of file extensions for which the override
* should apply, delimited by a 'pipe' character
* (e.g. "md|sms|gg")
* Permitted file extensions are limited to those
* included in retro_system_info::valid_extensions
* and/or retro_subsystem_rom_info::valid_extensions */
const char *extensions;
/* Overrides the need_fullpath value set in
* retro_system_info and/or retro_subsystem_rom_info.
* To reiterate:
*
* If need_fullpath is true and retro_load_game() is called:
* - retro_game_info::path is guaranteed to contain a valid
* path to an existent file
* - retro_game_info::data and retro_game_info::size are invalid
*
* If need_fullpath is false and retro_load_game() is called:
* - retro_game_info::path may be NULL
* - retro_game_info::data and retro_game_info::size are guaranteed
* to be valid
*
* In addition:
*
* If need_fullpath is true and retro_load_game() is called:
* - retro_game_info_ext::full_path is guaranteed to contain a valid
* path to an existent file
* - retro_game_info_ext::archive_path may be NULL
* - retro_game_info_ext::archive_file may be NULL
* - retro_game_info_ext::dir is guaranteed to contain a valid path
* to the directory in which the content file exists
* - retro_game_info_ext::name is guaranteed to contain the
* basename of the content file, without extension
* - retro_game_info_ext::ext is guaranteed to contain the
* extension of the content file in lower case format
* - retro_game_info_ext::data and retro_game_info_ext::size
* are invalid
*
* If need_fullpath is false and retro_load_game() is called:
* - If retro_game_info_ext::file_in_archive is false:
* - retro_game_info_ext::full_path is guaranteed to contain
* a valid path to an existent file
* - retro_game_info_ext::archive_path may be NULL
* - retro_game_info_ext::archive_file may be NULL
* - retro_game_info_ext::dir is guaranteed to contain a
* valid path to the directory in which the content file exists
* - retro_game_info_ext::name is guaranteed to contain the
* basename of the content file, without extension
* - retro_game_info_ext::ext is guaranteed to contain the
* extension of the content file in lower case format
* - If retro_game_info_ext::file_in_archive is true:
* - retro_game_info_ext::full_path may be NULL
* - retro_game_info_ext::archive_path is guaranteed to
* contain a valid path to an existent compressed file
* inside which the content file is located
* - retro_game_info_ext::archive_file is guaranteed to
* contain a valid path to an existent content file
* inside the compressed file referred to by
* retro_game_info_ext::archive_path
* e.g. for a compressed file '/path/to/foo.zip'
* containing 'bar.sfc'
* > retro_game_info_ext::archive_path will be '/path/to/foo.zip'
* > retro_game_info_ext::archive_file will be 'bar.sfc'
* - retro_game_info_ext::dir is guaranteed to contain a
* valid path to the directory in which the compressed file
* (containing the content file) exists
* - retro_game_info_ext::name is guaranteed to contain
* EITHER
* 1) the basename of the compressed file (containing
* the content file), without extension
* OR
* 2) the basename of the content file inside the
* compressed file, without extension
* In either case, a core should consider 'name' to
* be the canonical name/ID of the the content file
* - retro_game_info_ext::ext is guaranteed to contain the
* extension of the content file inside the compressed file,
* in lower case format
* - retro_game_info_ext::data and retro_game_info_ext::size are
* guaranteed to be valid */
bool need_fullpath;
/* If need_fullpath is false, specifies whether the content
* data buffer available in retro_load_game() is 'persistent'
*
* If persistent_data is false and retro_load_game() is called:
* - retro_game_info::data and retro_game_info::size
* are valid only until retro_load_game() returns
* - retro_game_info_ext::data and retro_game_info_ext::size
* are valid only until retro_load_game() returns
*
* If persistent_data is true and retro_load_game() is called:
* - retro_game_info::data and retro_game_info::size
* are valid until retro_deinit() returns
* - retro_game_info_ext::data and retro_game_info_ext::size
* are valid until retro_deinit() returns */
bool persistent_data;
};
/* Similar to retro_game_info, but provides extended
* information about the source content file and
* game memory buffer status.
* And array of retro_game_info_ext is returned by
* RETRO_ENVIRONMENT_GET_GAME_INFO_EXT
* NOTE: In the following descriptions, references to
* retro_load_game() may be replaced with
* retro_load_game_special() */
struct retro_game_info_ext
{
/* - If file_in_archive is false, contains a valid
* path to an existent content file (UTF-8 encoded)
* - If file_in_archive is true, may be NULL */
const char *full_path;
/* - If file_in_archive is false, may be NULL
* - If file_in_archive is true, contains a valid path
* to an existent compressed file inside which the
* content file is located (UTF-8 encoded) */
const char *archive_path;
/* - If file_in_archive is false, may be NULL
* - If file_in_archive is true, contain a valid path
* to an existent content file inside the compressed
* file referred to by archive_path (UTF-8 encoded)
* e.g. for a compressed file '/path/to/foo.zip'
* containing 'bar.sfc'
* > archive_path will be '/path/to/foo.zip'
* > archive_file will be 'bar.sfc' */
const char *archive_file;
/* - If file_in_archive is false, contains a valid path
* to the directory in which the content file exists
* (UTF-8 encoded)
* - If file_in_archive is true, contains a valid path
* to the directory in which the compressed file
* (containing the content file) exists (UTF-8 encoded) */
const char *dir;
/* Contains the canonical name/ID of the content file
* (UTF-8 encoded). Intended for use when identifying
* 'complementary' content named after the loaded file -
* i.e. companion data of a different format (a CD image
* required by a ROM), texture packs, internally handled
* save files, etc.
* - If file_in_archive is false, contains the basename
* of the content file, without extension
* - If file_in_archive is true, then string is
* implementation specific. A frontend may choose to
* set a name value of:
* EITHER
* 1) the basename of the compressed file (containing
* the content file), without extension
* OR
* 2) the basename of the content file inside the
* compressed file, without extension
* RetroArch sets the 'name' value according to (1).
* A frontend that supports routine loading of
* content from archives containing multiple unrelated
* content files may set the 'name' value according
* to (2). */
const char *name;
/* - If file_in_archive is false, contains the extension
* of the content file in lower case format
* - If file_in_archive is true, contains the extension
* of the content file inside the compressed file,
* in lower case format */
const char *ext;
/* String of implementation specific meta-data. */
const char *meta;
/* Memory buffer of loaded game content. Will be NULL:
* IF
* - retro_system_info::need_fullpath is true and
* retro_system_content_info_override::need_fullpath
* is unset
* OR
* - retro_system_content_info_override::need_fullpath
* is true */
const void *data;
/* Size of game content memory buffer, in bytes */
size_t size;
/* True if loaded content file is inside a compressed
* archive */
bool file_in_archive;
/* - If data is NULL, value is unset/ignored
* - If data is non-NULL:
* - If persistent_data is false, data and size are
* valid only until retro_load_game() returns
* - If persistent_data is true, data and size are
* are valid until retro_deinit() returns */
bool persistent_data;
};
/**
* Parameters describing the size and shape of the video frame.
* @see retro_system_av_info
* @see RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO
* @see RETRO_ENVIRONMENT_SET_GEOMETRY
* @see retro_get_system_av_info
*/
struct retro_game_geometry
{
/**
* Nominal video width of game, in pixels.
* This will typically be the emulated platform's native video width
* (or its smallest, if the original hardware supports multiple resolutions).
*/
unsigned base_width;
/**
* Nominal video height of game, in pixels.
* This will typically be the emulated platform's native video height
* (or its smallest, if the original hardware supports multiple resolutions).
*/
unsigned base_height;
/**
* Maximum possible width of the game screen, in pixels.
* This will typically be the emulated platform's maximum video width.
* For cores that emulate platforms with multiple screens (such as the Nintendo DS),
* this should assume the core's widest possible screen layout (e.g. side-by-side).
* For cores that support upscaling the resolution,
* this should assume the highest supported scale factor is active.
*/
unsigned max_width;
/**
* Maximum possible height of the game screen, in pixels.
* This will typically be the emulated platform's maximum video height.
* For cores that emulate platforms with multiple screens (such as the Nintendo DS),
* this should assume the core's tallest possible screen layout (e.g. vertical).
* For cores that support upscaling the resolution,
* this should assume the highest supported scale factor is active.
*/
unsigned max_height; /* Maximum possible height of game. */
/**
* Nominal aspect ratio of game.
* If zero or less,
* an aspect ratio of <tt>base_width / base_height</tt> is assumed.
*
* @note A frontend may ignore this setting.
*/
float aspect_ratio;
};
/**
* Parameters describing the timing of the video and audio.
* @see retro_system_av_info
* @see RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO
* @see retro_get_system_av_info
*/
struct retro_system_timing
{
/** Video output refresh rate, in frames per second. */
double fps;
/** The audio output sample rate, in Hz. */
double sample_rate;
};
/**
* Configures how the core's audio and video should be updated.
* @see RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO
* @see retro_get_system_av_info
*/
struct retro_system_av_info
{
/** Parameters describing the size and shape of the video frame. */
struct retro_game_geometry geometry;
/** Parameters describing the timing of the video and audio. */
struct retro_system_timing timing;
};
/** @defgroup SET_CORE_OPTIONS Core Options
* @{
*/
/**
* Represents \ref RETRO_ENVIRONMENT_GET_VARIABLE "a core option query".
*
* @note In \ref RETRO_ENVIRONMENT_SET_VARIABLES
* (which is a deprecated API),
* this \c struct serves as an option definition.
*
* @see RETRO_ENVIRONMENT_GET_VARIABLE
*/
struct retro_variable
{
/**
* A unique key identifying this option.
*
* Should be a key for an option that was previously defined
* with \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 or similar.
*
* Should be prefixed with the core's name
* to minimize the risk of collisions with another core's options,
* as frontends are not required to use a namespacing scheme for storing options.
* For example, a core named "foo" might define an option named "foo_option".
*
* @note In \ref RETRO_ENVIRONMENT_SET_VARIABLES
* (which is a deprecated API),
* this field is used to define an option
* named by this key.
*/
const char *key;
/**
* Value to be obtained.
*
* Set by the frontend to \c NULL if
* the option named by \ref key does not exist.
*
* @note In \ref RETRO_ENVIRONMENT_SET_VARIABLES
* (which is a deprecated API),
* this field is set by the core to define the possible values
* for an option named by \ref key.
* When used this way, it must be formatted as follows:
* @li The text before the first ';' is the option's human-readable title.
* @li A single space follows the ';'.
* @li The rest of the string is a '|'-delimited list of possible values,
* with the first one being the default.
*/
const char *value;
};
/**
* An argument that's used to show or hide a core option in the frontend.
*
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY
*/
struct retro_core_option_display
{
/**
* The key for a core option that was defined with \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2,
* \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL,
* or their legacy equivalents.
*/
const char *key;
/**
* Whether the option named by \c key
* should be displayed to the player in the frontend's core options menu.
*
* @note This value is a hint, \em not a requirement;
* the frontend is free to ignore this field.
*/
bool visible;
};
/**
* The maximum number of choices that can be defined for a given core option.
*
* This limit was chosen as a compromise between
* a core's flexibility and a streamlined user experience.
*
* @note A guiding principle of libretro's API design is that
* all common interactions (gameplay, menu navigation, etc.)
* should be possible without a keyboard.
*
* If you need more than 128 choices for a core option,
* consider simplifying your option structure.
* Here are some ideas:
*
* \li If a core option represents a numeric value,
* consider reducing the option's granularity
* (e.g. define time limits in increments of 5 seconds instead of 1 second).
* Providing a fixed set of values based on experimentation
* is also a good idea.
* \li If a core option represents a dynamically-built list of files,
* consider leaving out files that won't be useful.
* For example, if a core allows the player to choose a specific BIOS file,
* it can omit files of the wrong length or without a valid header.
*
* @see retro_core_option_definition
* @see retro_core_option_v2_definition
*/
#define RETRO_NUM_CORE_OPTION_VALUES_MAX 128
/**
* A descriptor for a particular choice within a core option.
*
* @note All option values are represented as strings.
* If you need to represent any other type,
* parse the string in \ref value.
*
* @see retro_core_option_v2_category
*/
struct retro_core_option_value
{
/**
* The option value that the frontend will serialize.
*
* Must not be \c NULL or empty.
* No other hard limits are placed on this value's contents,
* but here are some suggestions:
*
* \li If the value represents a number,
* don't include any non-digit characters (units, separators, etc.).
* Instead, include that information in \c label.
* This will simplify parsing.
* \li If the value represents a file path,
* store it as a relative path with respect to one of the common libretro directories
* (e.g. \ref RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY "the system directory"
* or \ref RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY "the save directory"),
* and use forward slashes (\c "/") as directory separators.
* This will simplify cloud storage if supported by the frontend,
* as the same file may be used on multiple devices.
*/
const char *value;
/**
* Human-readable name for \c value that the frontend should show to players.
*
* May be \c NULL, in which case the frontend
* should display \c value itself.
*
* Here are some guidelines for writing a good label:
*
* \li Make the option labels obvious
* so that they don't need to be explained in the description.
* \li Keep labels short, and don't use unnecessary words.
* For example, "OpenGL" is a better label than "OpenGL Mode".
* \li If the option represents a number,
* consider adding units, separators, or other punctuation
* into the label itself.
* For example, "5 seconds" is a better label than "5".
* \li If the option represents a number, use intuitive units
* that don't take a lot of digits to express.
* For example, prefer "1 minute" over "60 seconds" or "60,000 milliseconds".
*/
const char *label;
};
/**
* @copybrief retro_core_option_v2_definition
*
* @deprecated Use \ref retro_core_option_v2_definition instead,
* as it supports categorizing options into groups.
* Only use this \c struct to support older frontends or cores.
*
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL
*/
struct retro_core_option_definition
{
/** @copydoc retro_core_option_v2_definition::key */
const char *key;
/** @copydoc retro_core_option_v2_definition::desc */
const char *desc;
/** @copydoc retro_core_option_v2_definition::info */
const char *info;
/** @copydoc retro_core_option_v2_definition::values */
struct retro_core_option_value values[RETRO_NUM_CORE_OPTION_VALUES_MAX];
/** @copydoc retro_core_option_v2_definition::default_value */
const char *default_value;
};
#ifdef __PS3__
#undef local
#endif
/**
* A variant of \ref retro_core_options that supports internationalization.
*
* @deprecated Use \ref retro_core_options_v2_intl instead,
* as it supports categorizing options into groups.
* Only use this \c struct to support older frontends or cores.
*
* @see retro_core_options
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL
* @see RETRO_ENVIRONMENT_GET_LANGUAGE
* @see retro_language
*/
struct retro_core_options_intl
{
/** @copydoc retro_core_options_v2_intl::us */
struct retro_core_option_definition *us;
/** @copydoc retro_core_options_v2_intl::local */
struct retro_core_option_definition *local;
};
/**
* A descriptor for a group of related core options.
*
* Here's an example category:
*
* @code
* {
* "cpu",
* "CPU Emulation",
* "Settings for CPU quirks."
* }
* @endcode
*
* @see retro_core_options_v2
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL
*/
struct retro_core_option_v2_category
{
/**
* A string that uniquely identifies this category within the core's options.
* Any \c retro_core_option_v2_definition whose \c category_key matches this
* is considered to be within this category.
* Different cores may use the same category keys,
* so namespacing them is not necessary.
* Valid characters are <tt>[a-zA-Z0-9_-]</tt>.
*
* Frontends should use this category to organize core options,
* but may customize this category's presentation in other ways.
* For example, a frontend may use common keys like "audio" or "gfx"
* to select an appropriate icon in its UI.
*
* Required; must not be \c NULL.
*/
const char *key;
/**
* A brief human-readable name for this category,
* intended for the frontend to display to the player.
* This should be a name that's concise and descriptive, such as "Audio" or "Video".
*
* Required; must not be \c NULL.
*/
const char *desc;
/**
* A human-readable description for this category,
* intended for the frontend to display to the player
* as secondary help text (e.g. a sublabel or a tooltip).
* Optional; may be \c NULL or an empty string.
*/
const char *info;
};
/**
* A descriptor for a particular core option and the values it may take.
*
* Supports categorizing options into groups,
* so as not to overwhelm the player.
*
* @see retro_core_option_v2_category
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL
*/
struct retro_core_option_v2_definition
{
/**
* A unique identifier for this option that cores may use
* \ref RETRO_ENVIRONMENT_GET_VARIABLE "to query its value from the frontend".
* Must be unique within this core.
*
* Should be unique globally;
* the recommended method for doing so
* is to prefix each option with the core's name.
* For example, an option that controls the resolution for a core named "foo"
* should be named \c "foo_resolution".
*
* Valid key characters are in the set <tt>[a-zA-Z0-9_-]</tt>.
*/
const char *key;
/**
* A human-readable name for this option,
* intended to be displayed by frontends that don't support
* categorizing core options.
*
* Required; must not be \c NULL or empty.
*/
const char *desc;
/**
* A human-readable name for this option,
* intended to be displayed by frontends that support
* categorizing core options.
*
* This version may be slightly more concise than \ref desc,
* as it can rely on the structure of the options menu.
* For example, "Interface" is a good \c desc_categorized,
* as it can be displayed as a sublabel for a "Network" category.
* For \c desc, "Network Interface" would be more suitable.
*
* Optional; if this field or \c category_key is empty or \c NULL,
* \c desc will be used instead.
*/
const char *desc_categorized;
/**
* A human-readable description of this option and its effects,
* intended to be displayed by frontends that don't support
* categorizing core options.
*
* @details Intended to be displayed as secondary help text,
* such as a tooltip or a sublabel.
*
* Here are some suggestions for writing a good description:
*
* \li Avoid technical jargon unless this option is meant for advanced users.
* If unavoidable, suggest one of the default options for those unsure.
* \li Don't repeat the option name in the description;
* instead, describe what the option name means.
* \li If an option requires a core restart or game reset to take effect,
* be sure to say so.
* \li Try to make the option labels obvious
* so that they don't need to be explained in the description.
*
* Optional; may be \c NULL.
*/
const char *info;
/**
* @brief A human-readable description of this option and its effects,
* intended to be displayed by frontends that support
* categorizing core options.
*
* This version is provided to accommodate descriptions
* that reference other options by name,
* as options may have different user-facing names
* depending on whether the frontend supports categorization.
*
* @copydetails info
*
* If empty or \c NULL, \c info will be used instead.
* Will be ignored if \c category_key is empty or \c NULL.
*/
const char *info_categorized;
/**
* The key of the category that this option belongs to.
*
* Optional; if equal to \ref retro_core_option_v2_category::key "a defined category",
* then this option shall be displayed by the frontend
* next to other options in this same category,
* assuming it supports doing so.
* Option categories are intended to be displayed in a submenu,
* but this isn't a hard requirement.
*
* If \c NULL, empty, or not equal to a defined category,
* then this option is considered uncategorized
* and the frontend shall display it outside of any category
* (most likely at a top-level menu).
*
* @see retro_core_option_v2_category
*/
const char *category_key;
/**
* One or more possible values for this option,
* up to the limit of \ref RETRO_NUM_CORE_OPTION_VALUES_MAX.
*
* Terminated by a \c { NULL, NULL } element,
* although frontends should work even if all elements are used.
*/
struct retro_core_option_value values[RETRO_NUM_CORE_OPTION_VALUES_MAX];
/**
* The default value for this core option.
* Used if it hasn't been set, e.g. for new cores.
* Must equal one of the \ref value members in the \c values array,
* or else this option will be ignored.
*/
const char *default_value;
};
/**
* A set of core option descriptors and the categories that group them,
* suitable for enabling a core to be customized.
*
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
*/
struct retro_core_options_v2
{
/**
* An array of \ref retro_core_option_v2_category "option categories",
* terminated by a zeroed-out category \c struct.
*
* Will be ignored if the frontend doesn't support core option categories.
*
* If \c NULL or ignored, all options will be treated as uncategorized.
* This most likely means that a frontend will display them at a top-level menu
* without any kind of hierarchy or grouping.
*/
struct retro_core_option_v2_category *categories;
/**
* An array of \ref retro_core_option_v2_definition "core option descriptors",
* terminated by a zeroed-out definition \c struct.
*
* Required; must not be \c NULL.
*/
struct retro_core_option_v2_definition *definitions;
};
/**
* A variant of \ref retro_core_options_v2 that supports internationalization.
*
* @see retro_core_options_v2
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL
* @see RETRO_ENVIRONMENT_GET_LANGUAGE
* @see retro_language
*/
struct retro_core_options_v2_intl
{
/**
* Pointer to a core options set
* whose text is written in American English.
*
* This may be passed to \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 as-is
* if not using \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL.
*
* Required; must not be \c NULL.
*/
struct retro_core_options_v2 *us;
/**
* Pointer to a core options set
* whose text is written in one of libretro's \ref retro_language "supported languages",
* most likely the one returned by \ref RETRO_ENVIRONMENT_GET_LANGUAGE.
*
* Structure is the same, but usage is slightly different:
*
* \li All text (except for keys and option values)
* should be written in whichever language
* is returned by \c RETRO_ENVIRONMENT_GET_LANGUAGE.
* \li All fields besides keys and option values may be \c NULL,
* in which case the corresponding string in \c us
* is used instead.
* \li All \ref retro_core_option_v2_definition::default_value "default option values"
* are taken from \c us.
* The defaults in this field are ignored.
*
* May be \c NULL, in which case \c us is used instead.
*/
struct retro_core_options_v2 *local;
};
/**
* Called by the frontend to determine if any core option's visibility has changed.
*
* Each time a frontend sets a core option,
* it should call this function to see if
* any core option should be made visible or invisible.
*
* May also be called after \ref retro_load_game "loading a game",
* to determine what the initial visibility of each option should be.
*
* Within this function, the core must update the visibility
* of any dynamically-hidden options
* using \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY.
*
* @note All core options are visible by default,
* even during this function's first call.
*
* @return \c true if any core option's visibility was adjusted
* since the last call to this function.
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY
* @see retro_core_option_display
*/
typedef bool (RETRO_CALLCONV *retro_core_options_update_display_callback_t)(void);
/**
* Callback registered by the core for the frontend to use
* when setting the visibility of each core option.
*
* @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY
* @see retro_core_option_display
*/
struct retro_core_options_update_display_callback
{
/**
* @copydoc retro_core_options_update_display_callback_t
*
* Set by the core.
*/
retro_core_options_update_display_callback_t callback;
};
/** @} */
struct retro_game_info
{
const char *path; /* Path to game, UTF-8 encoded.
* Sometimes used as a reference for building other paths.
* May be NULL if game was loaded from stdin or similar,
* but in this case some cores will be unable to load `data`.
* So, it is preferable to fabricate something here instead
* of passing NULL, which will help more cores to succeed.
* retro_system_info::need_fullpath requires
* that this path is valid. */
const void *data; /* Memory buffer of loaded game. Will be NULL
* if need_fullpath was set. */
size_t size; /* Size of memory buffer. */
const char *meta; /* String of implementation specific meta-data. */
};
/** @defgroup GET_CURRENT_SOFTWARE_FRAMEBUFFER Frontend-Owned Framebuffers
* @{
*/
/** @defgroup RETRO_MEMORY_ACCESS Framebuffer Memory Access Types
* @{
*/
/** Indicates that core will write to the framebuffer returned by the frontend. */
#define RETRO_MEMORY_ACCESS_WRITE (1 << 0)
/** Indicates that the core will read from the framebuffer returned by the frontend. */
#define RETRO_MEMORY_ACCESS_READ (1 << 1)
/** @} */
/** @defgroup RETRO_MEMORY_TYPE Framebuffer Memory Types
* @{
*/
/**
* Indicates that the returned framebuffer's memory is cached.
* If not set, random access to the buffer may be very slow.
*/
#define RETRO_MEMORY_TYPE_CACHED (1 << 0)
/** @} */
/**
* A frame buffer owned by the frontend that a core may use for rendering.
*
* @see GET_CURRENT_SOFTWARE_FRAMEBUFFER
* @see retro_video_refresh_t
*/
struct retro_framebuffer
{
/**
* Pointer to the beginning of the framebuffer provided by the frontend.
* The initial contents of this buffer are unspecified,
* as is the means used to map the memory;
* this may be defined in software,
* or it may be GPU memory mapped to RAM.
*
* If the framebuffer is used,
* this pointer must be passed to \c retro_video_refresh_t as-is.
* It is undefined behavior to pass an offset to this pointer.
*
* @warning This pointer is only guaranteed to be valid
* for the duration of the same \c retro_run iteration
* \ref GET_CURRENT_SOFTWARE_FRAMEBUFFER "that requested the framebuffer".
* Reuse of this pointer is undefined.
*/
void *data;
/**
* The width of the framebuffer given in \c data, in pixels.
* Set by the core.
*
* @warning If the framebuffer is used,
* this value must be passed to \c retro_video_refresh_t as-is.
* It is undefined behavior to try to render \c data with any other width.
*/
unsigned width;
/**
* The height of the framebuffer given in \c data, in pixels.
* Set by the core.
*
* @warning If the framebuffer is used,
* this value must be passed to \c retro_video_refresh_t as-is.
* It is undefined behavior to try to render \c data with any other height.
*/
unsigned height;
/**
* The distance between the start of one scanline and the beginning of the next, in bytes.
* In practice this is usually equal to \c width times the pixel size,
* but that's not guaranteed.
* Sometimes called the "stride".
*
* @setby{frontend}
* @warning If the framebuffer is used,
* this value must be passed to \c retro_video_refresh_t as-is.
* It is undefined to try to render \c data with any other pitch.
*/
size_t pitch;
/**
* The pixel format of the returned framebuffer.
* May be different than the format specified by the core in \c RETRO_ENVIRONMENT_SET_PIXEL_FORMAT,
* e.g. due to conversions.
* Set by the frontend.
*
* @see RETRO_ENVIRONMENT_SET_PIXEL_FORMAT
*/
enum retro_pixel_format format;
/**
* One or more \ref RETRO_MEMORY_ACCESS "memory access flags"
* that specify how the core will access the memory in \c data.
*
* @setby{core}
*/
unsigned access_flags;
/**
* Zero or more \ref RETRO_MEMORY_TYPE "memory type flags"
* that describe how the framebuffer's memory has been mapped.
*
* @setby{frontend}
*/
unsigned memory_flags;
};
/** @} */
/** @defgroup SET_FASTFORWARDING_OVERRIDE Fast-Forward Override
* @{
*/
/**
* Parameters that govern when and how the core takes control
* of fast-forwarding mode.
*/
struct retro_fastforwarding_override
{
/**
* The factor by which the core will be sped up
* when \c fastforward is \c true.
* This value is used as follows:
*
* @li A value greater than 1.0 will run the core at
* the specified multiple of normal speed.
* For example, a value of 5.0
* combined with a normal target rate of 60 FPS
* will result in a target rate of 300 FPS.
* The actual rate may be lower if the host's hardware can't keep up.
* @li A value of 1.0 will run the core at normal speed.
* @li A value between 0.0 (inclusive) and 1.0 (exclusive)
* will run the core as fast as the host system can manage.
* @li A negative value will let the frontend choose a factor.
* @li An infinite value or \c NaN results in undefined behavior.
*
* @attention Setting this value to less than 1.0 will \em not
* slow down the core.
*/
float ratio;
/**
* If \c true, the frontend should activate fast-forwarding
* until this field is set to \c false or the core is unloaded.
*/
bool fastforward;
/**
* If \c true, the frontend should display an on-screen notification or icon
* while \c fastforward is \c true (where supported).
* Otherwise, the frontend should not display any such notification.
*/
bool notification;
/**
* If \c true, the core has exclusive control
* over enabling and disabling fast-forwarding
* via the \c fastforward field.
* The frontend will not be able to start or stop fast-forwarding
* until this field is set to \c false or the core is unloaded.
*/
bool inhibit_toggle;
};
/** @} */
/**
* During normal operation.
*
* @note Rate will be equal to the core's internal FPS.
*/
#define RETRO_THROTTLE_NONE 0
/**
* While paused or stepping single frames.
*
* @note Rate will be 0.
*/
#define RETRO_THROTTLE_FRAME_STEPPING 1
/**
* During fast forwarding.
*
* @note Rate will be 0 if not specifically limited to a maximum speed.
*/
#define RETRO_THROTTLE_FAST_FORWARD 2
/**
* During slow motion.
*
* @note Rate will be less than the core's internal FPS.
*/
#define RETRO_THROTTLE_SLOW_MOTION 3
/**
* While rewinding recorded save states.
*
* @note Rate can vary depending on the rewind speed or be 0 if the frontend
* is not aiming for a specific rate.
*/
#define RETRO_THROTTLE_REWINDING 4
/**
* While vsync is active in the video driver, and the target refresh rate is lower than the core's internal FPS.
*
* @note Rate is the target refresh rate.
*/
#define RETRO_THROTTLE_VSYNC 5
/**
* When the frontend does not throttle in any way.
*
* @note Rate will be 0. An example could be if no vsync or audio output is active.
*/
#define RETRO_THROTTLE_UNBLOCKED 6
/**
* Details about the actual rate an implementation is calling \c retro_run() at.
*
* @see RETRO_ENVIRONMENT_GET_THROTTLE_STATE
*/
struct retro_throttle_state
{
/**
* The current throttling mode.
*
* @note Should be one of the \c RETRO_THROTTLE_* values.
* @see RETRO_THROTTLE_NONE
* @see RETRO_THROTTLE_FRAME_STEPPING
* @see RETRO_THROTTLE_FAST_FORWARD
* @see RETRO_THROTTLE_SLOW_MOTION
* @see RETRO_THROTTLE_REWINDING
* @see RETRO_THROTTLE_VSYNC
* @see RETRO_THROTTLE_UNBLOCKED
*/
unsigned mode;
/**
* How many times per second the frontend aims to call retro_run.
*
* @note Depending on the mode, it can be 0 if there is no known fixed rate.
* This won't be accurate if the total processing time of the core and
* the frontend is longer than what is available for one frame.
*/
float rate;
};
/** @defgroup GET_MICROPHONE_INTERFACE Microphone Interface
* @{
*/
/**
* Opaque handle to a microphone that's been opened for use.
* The underlying object is accessed or created with \c retro_microphone_interface_t.
*/
typedef struct retro_microphone retro_microphone_t;
/**
* Parameters for configuring a microphone.
* Some of these might not be honored,
* depending on the available hardware and driver configuration.
*/
typedef struct retro_microphone_params
{
/**
* The desired sample rate of the microphone's input, in Hz.
* The microphone's input will be resampled,
* so cores can ask for whichever frequency they need.
*
* If zero, some reasonable default will be provided by the frontend
* (usually from its config file).
*
* @see retro_get_mic_rate_t
*/
unsigned rate;
} retro_microphone_params_t;
/**
* @copydoc retro_microphone_interface::open_mic
*/
typedef retro_microphone_t *(RETRO_CALLCONV *retro_open_mic_t)(const retro_microphone_params_t *params);
/**
* @copydoc retro_microphone_interface::close_mic
*/
typedef void (RETRO_CALLCONV *retro_close_mic_t)(retro_microphone_t *microphone);
/**
* @copydoc retro_microphone_interface::get_params
*/
typedef bool (RETRO_CALLCONV *retro_get_mic_params_t)(const retro_microphone_t *microphone, retro_microphone_params_t *params);
/**
* @copydoc retro_microphone_interface::set_mic_state
*/
typedef bool (RETRO_CALLCONV *retro_set_mic_state_t)(retro_microphone_t *microphone, bool state);
/**
* @copydoc retro_microphone_interface::get_mic_state
*/
typedef bool (RETRO_CALLCONV *retro_get_mic_state_t)(const retro_microphone_t *microphone);
/**
* @copydoc retro_microphone_interface::read_mic
*/
typedef int (RETRO_CALLCONV *retro_read_mic_t)(retro_microphone_t *microphone, int16_t* samples, size_t num_samples);
/**
* The current version of the microphone interface.
* Will be incremented whenever \c retro_microphone_interface or \c retro_microphone_params_t
* receive new fields.
*
* Frontends using cores built against older mic interface versions
* should not access fields introduced in newer versions.
*/
#define RETRO_MICROPHONE_INTERFACE_VERSION 1
/**
* An interface for querying the microphone and accessing data read from it.
*
* @see RETRO_ENVIRONMENT_GET_MICROPHONE_INTERFACE
*/
struct retro_microphone_interface
{
/**
* The version of this microphone interface.
* Set by the core to request a particular version,
* and set by the frontend to indicate the returned version.
* 0 indicates that the interface is invalid or uninitialized.
*/
unsigned interface_version;
/**
* Initializes a new microphone.
* Assuming that microphone support is enabled and provided by the frontend,
* cores may call this function whenever necessary.
* A microphone could be opened throughout a core's lifetime,
* or it could wait until a microphone is plugged in to the emulated device.
*
* The returned handle will be valid until it's freed,
* even if the audio driver is reinitialized.
*
* This function is not guaranteed to be thread-safe.
*
* @param[in] args Parameters used to create the microphone.
* May be \c NULL, in which case the default value of each parameter will be used.
*
* @returns Pointer to the newly-opened microphone,
* or \c NULL if one couldn't be opened.
* This likely means that no microphone is plugged in and recognized,
* or the maximum number of supported microphones has been reached.
*
* @note Microphones are \em inactive by default;
* to begin capturing audio, call \c set_mic_state.
* @see retro_microphone_params_t
*/
retro_open_mic_t open_mic;
/**
* Closes a microphone that was initialized with \c open_mic.
* Calling this function will stop all microphone activity
* and free up the resources that it allocated.
* Afterwards, the handle is invalid and must not be used.
*
* A frontend may close opened microphones when unloading content,
* but this behavior is not guaranteed.
* Cores should close their microphones when exiting, just to be safe.
*
* @param microphone Pointer to the microphone that was allocated by \c open_mic.
* If \c NULL, this function does nothing.
*
* @note The handle might be reused if another microphone is opened later.
*/
retro_close_mic_t close_mic;
/**
* Returns the configured parameters of this microphone.
* These may differ from what was requested depending on
* the driver and device configuration.
*
* Cores should check these values before they start fetching samples.
*
* Will not change after the mic was opened.
*
* @param[in] microphone Opaque handle to the microphone
* whose parameters will be retrieved.
* @param[out] params The parameters object that the
* microphone's parameters will be copied to.
*
* @return \c true if the parameters were retrieved,
* \c false if there was an error.
*/
retro_get_mic_params_t get_params;
/**
* Enables or disables the given microphone.
* Microphones are disabled by default
* and must be explicitly enabled before they can be used.
* Disabled microphones will not process incoming audio samples,
* and will therefore have minimal impact on overall performance.
* Cores may enable microphones throughout their lifetime,
* or only for periods where they're needed.
*
* Cores that accept microphone input should be able to operate without it;
* we suggest substituting silence in this case.
*
* @param microphone Opaque handle to the microphone
* whose state will be adjusted.
* This will have been provided by \c open_mic.
* @param state \c true if the microphone should receive audio input,
* \c false if it should be idle.
* @returns \c true if the microphone's state was successfully set,
* \c false if \c microphone is invalid
* or if there was an error.
*/
retro_set_mic_state_t set_mic_state;
/**
* Queries the active state of a microphone at the given index.
* Will return whether the microphone is enabled,
* even if the driver is paused.
*
* @param microphone Opaque handle to the microphone
* whose state will be queried.
* @return \c true if the provided \c microphone is valid and active,
* \c false if not or if there was an error.
*/
retro_get_mic_state_t get_mic_state;
/**
* Retrieves the input processed by the microphone since the last call.
* \em Must be called every frame unless \c microphone is disabled,
* similar to how \c retro_audio_sample_batch_t works.
*
* @param[in] microphone Opaque handle to the microphone
* whose recent input will be retrieved.
* @param[out] samples The buffer that will be used to store the microphone's data.
* Microphone input is in mono (i.e. one number per sample).
* Should be large enough to accommodate the expected number of samples per frame;
* for example, a 44.1kHz sample rate at 60 FPS would require space for 735 samples.
* @param[in] num_samples The size of the data buffer in samples (\em not bytes).
* Microphone input is in mono, so a "frame" and a "sample" are equivalent in length here.
*
* @return The number of samples that were copied into \c samples.
* If \c microphone is pending driver initialization,
* this function will copy silence of the requested length into \c samples.
*
* Will return -1 if the microphone is disabled,
* the audio driver is paused,
* or there was an error.
*/
retro_read_mic_t read_mic;
};
/** @} */
/** @defgroup GET_DEVICE_POWER Device Power
* @{
*/
/**
* Describes how a device is being powered.
* @see RETRO_ENVIRONMENT_GET_DEVICE_POWER
*/
enum retro_power_state
{
/**
* Indicates that the frontend cannot report its power state at this time,
* most likely due to a lack of support.
*
* \c RETRO_ENVIRONMENT_GET_DEVICE_POWER will not return this value;
* instead, the environment callback will return \c false.
*/
RETRO_POWERSTATE_UNKNOWN = 0,
/**
* Indicates that the device is running on its battery.
* Usually applies to portable devices such as handhelds, laptops, and smartphones.
*/
RETRO_POWERSTATE_DISCHARGING,
/**
* Indicates that the device's battery is currently charging.
*/
RETRO_POWERSTATE_CHARGING,
/**
* Indicates that the device is connected to a power source
* and that its battery has finished charging.
*/
RETRO_POWERSTATE_CHARGED,
/**
* Indicates that the device is connected to a power source
* and that it does not have a battery.
* This usually suggests a desktop computer or a non-portable game console.
*/
RETRO_POWERSTATE_PLUGGED_IN
};
/**
* Indicates that an estimate is not available for the battery level or time remaining,
* even if the actual power state is known.
*/
#define RETRO_POWERSTATE_NO_ESTIMATE (-1)
/**
* Describes the power state of the device running the frontend.
* @see RETRO_ENVIRONMENT_GET_DEVICE_POWER
*/
struct retro_device_power
{
/**
* The current state of the frontend's power usage.
*/
enum retro_power_state state;
/**
* A rough estimate of the amount of time remaining (in seconds)
* before the device powers off.
* This value depends on a variety of factors,
* so it is not guaranteed to be accurate.
*
* Will be set to \c RETRO_POWERSTATE_NO_ESTIMATE if \c state does not equal \c RETRO_POWERSTATE_DISCHARGING.
* May still be set to \c RETRO_POWERSTATE_NO_ESTIMATE if the frontend is unable to provide an estimate.
*/
int seconds;
/**
* The approximate percentage of battery charge,
* ranging from 0 to 100 (inclusive).
* The device may power off before this reaches 0.
*
* The user might have configured their device
* to stop charging before the battery is full,
* so do not assume that this will be 100 in the \c RETRO_POWERSTATE_CHARGED state.
*/
int8_t percent;
};
/** @} */
/**
* @defgroup Callbacks
* @{
*/
/**
* Environment callback to give implementations a way of performing uncommon tasks.
*
* @note Extensible.
*
* @param cmd The command to run.
* @param data A pointer to the data associated with the command.
*
* @return Varies by callback,
* but will always return \c false if the command is not recognized.
*
* @see RETRO_ENVIRONMENT_SET_ROTATION
* @see retro_set_environment()
*/
typedef bool (RETRO_CALLCONV *retro_environment_t)(unsigned cmd, void *data);
/**
* Render a frame.
*
* @note For performance reasons, it is highly recommended to have a frame
* that is packed in memory, i.e. pitch == width * byte_per_pixel.
* Certain graphic APIs, such as OpenGL ES, do not like textures
* that are not packed in memory.
*
* @param data A pointer to the frame buffer data with a pixel format of 15-bit \c 0RGB1555 native endian, unless changed with \c RETRO_ENVIRONMENT_SET_PIXEL_FORMAT.
* @param width The width of the frame buffer, in pixels.
* @param height The height frame buffer, in pixels.
* @param pitch The width of the frame buffer, in bytes.
*
* @see retro_set_video_refresh()
* @see RETRO_ENVIRONMENT_SET_PIXEL_FORMAT
* @see retro_pixel_format
*/
typedef void (RETRO_CALLCONV *retro_video_refresh_t)(const void *data, unsigned width,
unsigned height, size_t pitch);
/**
* Renders a single audio frame. Should only be used if implementation generates a single sample at a time.
*
* @param left The left audio sample represented as a signed 16-bit native endian.
* @param right The right audio sample represented as a signed 16-bit native endian.
*
* @see retro_set_audio_sample()
* @see retro_set_audio_sample_batch()
*/
typedef void (RETRO_CALLCONV *retro_audio_sample_t)(int16_t left, int16_t right);
/**
* Renders multiple audio frames in one go.
*
* @note Only one of the audio callbacks must ever be used.
*
* @param data A pointer to the audio sample data pairs to render.
* @param frames The number of frames that are represented in the data. One frame
* is defined as a sample of left and right channels, interleaved.
* For example: <tt>int16_t buf[4] = { l, r, l, r };</tt> would be 2 frames.
*
* @return The number of samples that were processed.
*
* @see retro_set_audio_sample_batch()
* @see retro_set_audio_sample()
*/
typedef size_t (RETRO_CALLCONV *retro_audio_sample_batch_t)(const int16_t *data,
size_t frames);
/**
* Polls input.
*
* @see retro_set_input_poll()
*/
typedef void (RETRO_CALLCONV *retro_input_poll_t)(void);
/**
* Queries for input for player 'port'.
*
* @param port Which player 'port' to query.
* @param device Which device to query for. Will be masked with \c RETRO_DEVICE_MASK.
* @param index The input index to retrieve.
* The exact semantics depend on the device type given in \c device.
* @param id The ID of which value to query, like \c RETRO_DEVICE_ID_JOYPAD_B.
* @returns Depends on the provided arguments,
* but will return 0 if their values are unsupported
* by the frontend or the backing physical device.
* @note Specialization of devices such as \c RETRO_DEVICE_JOYPAD_MULTITAP that
* have been set with \c retro_set_controller_port_device() will still use the
* higher level \c RETRO_DEVICE_JOYPAD to request input.
*
* @see retro_set_input_state()
* @see RETRO_DEVICE_NONE
* @see RETRO_DEVICE_JOYPAD
* @see RETRO_DEVICE_MOUSE
* @see RETRO_DEVICE_KEYBOARD
* @see RETRO_DEVICE_LIGHTGUN
* @see RETRO_DEVICE_ANALOG
* @see RETRO_DEVICE_POINTER
*/
typedef int16_t (RETRO_CALLCONV *retro_input_state_t)(unsigned port, unsigned device,
unsigned index, unsigned id);
/**
* Sets the environment callback.
*
* @param cb The function which is used when making environment calls.
*
* @note Guaranteed to be called before \c retro_init().
*
* @see RETRO_ENVIRONMENT
*/
RETRO_API void retro_set_environment(retro_environment_t cb);
/**
* Sets the video refresh callback.
*
* @param cb The function which is used when rendering a frame.
*
* @note Guaranteed to have been called before the first call to \c retro_run() is made.
*/
RETRO_API void retro_set_video_refresh(retro_video_refresh_t cb);
/**
* Sets the audio sample callback.
*
* @param cb The function which is used when rendering a single audio frame.
*
* @note Guaranteed to have been called before the first call to \c retro_run() is made.
*/
RETRO_API void retro_set_audio_sample(retro_audio_sample_t cb);
/**
* Sets the audio sample batch callback.
*
* @param cb The function which is used when rendering multiple audio frames in one go.
*
* @note Guaranteed to have been called before the first call to \c retro_run() is made.
*/
RETRO_API void retro_set_audio_sample_batch(retro_audio_sample_batch_t cb);
/**
* Sets the input poll callback.
*
* @param cb The function which is used to poll the active input.
*
* @note Guaranteed to have been called before the first call to \c retro_run() is made.
*/
RETRO_API void retro_set_input_poll(retro_input_poll_t cb);
/**
* Sets the input state callback.
*
* @param cb The function which is used to query the input state.
*
*@note Guaranteed to have been called before the first call to \c retro_run() is made.
*/
RETRO_API void retro_set_input_state(retro_input_state_t cb);
/**
* @}
*/
/**
* Called by the frontend when initializing a libretro core.
*
* @warning There are many possible "gotchas" with global state in dynamic libraries.
* Here are some to keep in mind:
* <ul>
* <li>Do not assume that the core was loaded by the operating system
* for the first time within this call.
* It may have been statically linked or retained from a previous session.
* Consequently, cores must not rely on global variables being initialized
* to their default values before this function is called;
* this also goes for object constructors in C++.
* <li>Although C++ requires that constructors be called for global variables,
* it does not require that their destructors be called
* if stored within a dynamic library's global scope.
* <li>If the core is statically linked to the frontend,
* global variables may be initialized when the frontend itself is initially executed.
* </ul>
* @see retro_deinit
*/
RETRO_API void retro_init(void);
/**
* Called by the frontend when deinitializing a libretro core.
* The core must release all of its allocated resources before this function returns.
*
* @warning There are many possible "gotchas" with global state in dynamic libraries.
* Here are some to keep in mind:
* <ul>
* <li>Do not assume that the operating system will unload the core after this function returns,
* as the core may be linked statically or retained in memory.
* Cores should use this function to clean up all allocated resources
* and reset all global variables to their default states.
* <li>Do not assume that this core won't be loaded again after this function returns.
* It may be kept in memory by the frontend for later use,
* or it may be statically linked.
* Therefore, all global variables should be reset to their default states within this function.
* <li>C++ does not require that destructors be called
* for variables within a dynamic library's global scope.
* Therefore, global objects that own dynamically-managed resources
* (such as \c std::string or <tt>std::vector</tt>)
* should be kept behind pointers that are explicitly deallocated within this function.
* </ul>
* @see retro_init
*/
RETRO_API void retro_deinit(void);
/**
* Retrieves which version of the libretro API is being used.
*
* @note This is used to validate ABI compatibility when the API is revised.
*
* @return Must return \c RETRO_API_VERSION.
*
* @see RETRO_API_VERSION
*/
RETRO_API unsigned retro_api_version(void);
/**
* Gets statically known system info.
*
* @note Can be called at any time, even before retro_init().
*
* @param info A pointer to a \c retro_system_info where the info is to be loaded into. This must be statically allocated.
*/
RETRO_API void retro_get_system_info(struct retro_system_info *info);
/**
* Gets information about system audio/video timings and geometry.
*
* @note Can be called only after \c retro_load_game() has successfully completed.
*
* @note The implementation of this function might not initialize every variable
* if needed. For example, \c geom.aspect_ratio might not be initialized if
* the core doesn't desire a particular aspect ratio.
*
* @param info A pointer to a \c retro_system_av_info where the audio/video information should be loaded into.
*
* @see retro_system_av_info
*/
RETRO_API void retro_get_system_av_info(struct retro_system_av_info *info);
/**
* Sets device to be used for player 'port'.
*
* By default, \c RETRO_DEVICE_JOYPAD is assumed to be plugged into all
* available ports.
*
* @note Setting a particular device type is not a guarantee that libretro cores
* will only poll input based on that particular device type. It is only a
* hint to the libretro core when a core cannot automatically detect the
* appropriate input device type on its own. It is also relevant when a
* core can change its behavior depending on device type.
*
* @note As part of the core's implementation of retro_set_controller_port_device,
* the core should call \c RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS to notify the
* frontend if the descriptions for any controls have changed as a
* result of changing the device type.
*
* @param port Which port to set the device for, usually indicates the player number.
* @param device Which device the given port is using. By default, \c RETRO_DEVICE_JOYPAD is assumed for all ports.
*
* @see RETRO_DEVICE_NONE
* @see RETRO_DEVICE_JOYPAD
* @see RETRO_DEVICE_MOUSE
* @see RETRO_DEVICE_KEYBOARD
* @see RETRO_DEVICE_LIGHTGUN
* @see RETRO_DEVICE_ANALOG
* @see RETRO_DEVICE_POINTER
* @see RETRO_ENVIRONMENT_SET_CONTROLLER_INFO
*/
RETRO_API void retro_set_controller_port_device(unsigned port, unsigned device);
/**
* Resets the currently-loaded game.
* Cores should treat this as a soft reset (i.e. an emulated reset button) if possible,
* but hard resets are acceptable.
*/
RETRO_API void retro_reset(void);
/**
* Runs the game for one video frame.
*
* During \c retro_run(), the \c retro_input_poll_t callback must be called at least once.
*
* @note If a frame is not rendered for reasons where a game "dropped" a frame,
* this still counts as a frame, and \c retro_run() should explicitly dupe
* a frame if \c RETRO_ENVIRONMENT_GET_CAN_DUPE returns true. In this case,
* the video callback can take a NULL argument for data.
*
* @see retro_input_poll_t
*/
RETRO_API void retro_run(void);
/**
* Returns the amount of data the implementation requires to serialize internal state (save states).
*
* @note Between calls to \c retro_load_game() and \c retro_unload_game(), the
* returned size is never allowed to be larger than a previous returned
* value, to ensure that the frontend can allocate a save state buffer once.
*
* @return The amount of data the implementation requires to serialize the internal state.
*
* @see retro_serialize()
*/
RETRO_API size_t retro_serialize_size(void);
/**
* Serializes the internal state.
*
* @param data A pointer to where the serialized data should be saved to.
* @param size The size of the memory.
*
* @return If failed, or size is lower than \c retro_serialize_size(), it
* should return false. On success, it will return true.
*
* @see retro_serialize_size()
* @see retro_unserialize()
*/
RETRO_API bool retro_serialize(void *data, size_t size);
/**
* Unserialize the given state data, and load it into the internal state.
*
* @return Returns true if loading the state was successful, false otherwise.
*
* @see retro_serialize()
*/
RETRO_API bool retro_unserialize(const void *data, size_t size);
/**
* Reset all the active cheats to their default disabled state.
*
* @see retro_cheat_set()
*/
RETRO_API void retro_cheat_reset(void);
/**
* Enable or disable a cheat.
*
* @param index The index of the cheat to act upon.
* @param enabled Whether to enable or disable the cheat.
* @param code A string of the code used for the cheat.
*
* @see retro_cheat_reset()
*/
RETRO_API void retro_cheat_set(unsigned index, bool enabled, const char *code);
/**
* Loads a game.
*
* @param game A pointer to a \c retro_game_info detailing information about the game to load.
* May be \c NULL if the core is loaded without content.
*
* @return Will return true when the game was loaded successfully, or false otherwise.
*
* @see retro_game_info
* @see RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME
*/
RETRO_API bool retro_load_game(const struct retro_game_info *game);
/**
* Called when the frontend has loaded one or more "special" content files,
* typically through subsystems.
*
* @note Only necessary for cores that support subsystems.
* Others may return \c false or delegate to <tt>retro_load_game</tt>.
*
* @param game_type The type of game to load,
* as determined by \c retro_subsystem_info.
* @param info A pointer to an array of \c retro_game_info objects
* providing information about the loaded content.
* @param num_info The number of \c retro_game_info objects passed into the info parameter.
* @return \c true if loading is successful, false otherwise.
* If the core returns \c false,
* the frontend should abort the core
* and return to its main menu (if applicable).
*
* @see RETRO_ENVIRONMENT_GET_GAME_INFO_EXT
* @see RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO
* @see retro_load_game()
* @see retro_subsystem_info
*/
RETRO_API bool retro_load_game_special(
unsigned game_type,
const struct retro_game_info *info, size_t num_info
);
/**
* Unloads the currently loaded game.
*
* @note This is called before \c retro_deinit(void).
*
* @see retro_load_game()
* @see retro_deinit()
*/
RETRO_API void retro_unload_game(void);
/**
* Gets the region of the actively loaded content as either \c RETRO_REGION_NTSC or \c RETRO_REGION_PAL.
* @note This refers to the region of the content's intended television standard,
* not necessarily the region of the content's origin.
* For emulated consoles that don't use either standard
* (e.g. handhelds or post-HD platforms),
* the core should return \c RETRO_REGION_NTSC.
* @return The region of the actively loaded content.
*
* @see RETRO_REGION_NTSC
* @see RETRO_REGION_PAL
*/
RETRO_API unsigned retro_get_region(void);
/**
* Get a region of memory.
*
* @param id The ID for the memory block that's desired to retrieve. Can be \c RETRO_MEMORY_SAVE_RAM, \c RETRO_MEMORY_RTC, \c RETRO_MEMORY_SYSTEM_RAM, or \c RETRO_MEMORY_VIDEO_RAM.
*
* @return A pointer to the desired region of memory, or NULL when not available.
*
* @see RETRO_MEMORY_SAVE_RAM
* @see RETRO_MEMORY_RTC
* @see RETRO_MEMORY_SYSTEM_RAM
* @see RETRO_MEMORY_VIDEO_RAM
*/
RETRO_API void *retro_get_memory_data(unsigned id);
/**
* Gets the size of the given region of memory.
*
* @param id The ID for the memory block to check the size of. Can be RETRO_MEMORY_SAVE_RAM, RETRO_MEMORY_RTC, RETRO_MEMORY_SYSTEM_RAM, or RETRO_MEMORY_VIDEO_RAM.
*
* @return The size of the region in memory, or 0 when not available.
*
* @see RETRO_MEMORY_SAVE_RAM
* @see RETRO_MEMORY_RTC
* @see RETRO_MEMORY_SYSTEM_RAM
* @see RETRO_MEMORY_VIDEO_RAM
*/
RETRO_API size_t retro_get_memory_size(unsigned id);
#ifdef __cplusplus
}
#endif
#endif
Reference in New Issue View Git Blame Copy Permalink