mirror/RetroArch
1
0
Fork 0
mirror of https://github.com/libretro/RetroArch synced 2025-01-30 12:32:52 +00:00
Code Issues Packages Projects Releases Wiki Activity
RetroArch/libretro-common/include/libretro.h
Viačasłaŭ 3019b926c2
Fix typos (#17068)
2024-10-01 17:36:33 -07:00

7829 lines
282 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, similar 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 continuously 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 for
* 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
/**
* Returns the "file browser" start directory of the frontend.
*
* This directory can serve as a start directory for the core in case it
* provides an internal way of loading content.
*
* @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_FILE_BROWSER_START_DIRECTORY 80
/**@}*/
/**
* @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 independent 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.
*
* Similarly 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 frontend 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 between 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 frames 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