2024-03-04 11:41:01 -05:00
/* Copyright (C) 2010-2020 The RetroArch team
2019-12-31 21:02:35 +01:00
*
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
* The following license statement only applies to this libretro API header ( libretro . h ) .
* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
*
* 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
2024-03-04 11:41:01 -05:00
extern " C " {
2019-12-31 21:02:35 +01:00
# 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
2024-03-04 11:41:01 -05:00
# 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
2019-12-31 21:02:35 +01:00
# endif
# ifndef RETRO_API
2024-03-04 11:41:01 -05:00
# 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
2019-12-31 21:02:35 +01:00
# endif
/* Used for checking API/ABI mismatches that can break libretro
* implementations .
* It is not incremented for compatible changes to the API .
*/
2024-03-04 11:41:01 -05:00
# define RETRO_API_VERSION 1
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/*
2019-12-31 21:02:35 +01:00
* Libretro ' s fundamental device abstractions .
*
* Libretro ' s input system consists of some standardized device types ,
* such as a joypad ( with / without analog ) , mouse , keyboard , lightgun
* and a pointer .
*
* The functionality of these devices are fixed , and individual cores
* 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 , and not having to worry about binding input
* correctly to arbitrary controller layouts .
*/
2024-03-04 11:41:01 -05:00
# define RETRO_DEVICE_TYPE_SHIFT 8
# define RETRO_DEVICE_MASK ((1 << RETRO_DEVICE_TYPE_SHIFT) - 1)
2019-12-31 21:02:35 +01:00
# define RETRO_DEVICE_SUBCLASS(base, id) (((id + 1) << RETRO_DEVICE_TYPE_SHIFT) | base)
/* Input disabled. */
2024-03-04 11:41:01 -05:00
# define RETRO_DEVICE_NONE 0
2019-12-31 21:02:35 +01:00
/* The JOYPAD is called RetroPad. It is essentially a Super Nintendo
* controller , but with additional L2 / R2 / L3 / R3 buttons , similar to a
* PS1 DualShock . */
2024-03-04 11:41:01 -05:00
# define RETRO_DEVICE_JOYPAD 1
2019-12-31 21:02:35 +01:00
/* The mouse is a simple mouse, similar to Super Nintendo's mouse.
* X and Y coordinates are reported relatively to last poll ( poll callback ) .
* It is up to the libretro implementation to keep track of where the mouse
* pointer is supposed to be on the screen .
* The frontend must make sure not to interfere with its own hardware
* mouse pointer .
*/
2024-03-04 11:41:01 -05:00
# define RETRO_DEVICE_MOUSE 2
2019-12-31 21:02:35 +01:00
/* KEYBOARD device lets one poll for raw key pressed.
* It is poll based , so input callback will return with the current
* pressed state .
* For event / text based keyboard input , see
* RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK .
*/
2024-03-04 11:41:01 -05:00
# define RETRO_DEVICE_KEYBOARD 3
2019-12-31 21:02:35 +01:00
/* LIGHTGUN device is similar to Guncon-2 for PlayStation 2.
* It reports X / Y coordinates in screen space ( similar to the pointer )
* in the range [ - 0x8000 , 0x7fff ] in both axes , with zero being center and
* - 0x8000 being out of bounds .
* As well as reporting on / off screen state . It features a trigger ,
* start / select buttons , auxiliary action buttons and a
* directional pad . A forced off - screen shot can be requested for
* auto - reloading function in some games .
*/
2024-03-04 11:41:01 -05:00
# define RETRO_DEVICE_LIGHTGUN 4
2019-12-31 21:02:35 +01:00
/* The ANALOG device is an extension to JOYPAD (RetroPad).
* Similar to DualShock2 it adds two analog sticks and all buttons can
* be analog . This is treated as a separate device type as it returns
* axis values in the full analog range of [ - 0x7fff , 0x7fff ] ,
* although some devices may return - 0x8000 .
* Positive X axis is right . Positive Y axis is down .
* Buttons are returned in the range [ 0 , 0x7fff ] .
* Only use ANALOG type when polling for analog values .
*/
2024-03-04 11:41:01 -05:00
# define RETRO_DEVICE_ANALOG 5
2019-12-31 21:02:35 +01:00
/* 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 ) , PRESSED returns 1 or 0.
*
* If using a mouse on a desktop , PRESSED will usually correspond to the
* left mouse button , but this is a frontend decision .
* 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 _PRESSED , coordinates can be extracted
* with _X , _Y for index = 0. One can then query _PRESSED , _X , _Y with
* index = 1 , and so on .
* Eventually _PRESSED will return false for an index . No further presses
* are registered at this point . */
2024-03-04 11:41:01 -05:00
# define RETRO_DEVICE_POINTER 6
2019-12-31 21:02:35 +01:00
/* Buttons for the RetroPad (JOYPAD).
* The placement of these is equivalent to placements on the
* Super Nintendo controller .
* L2 / R2 / L3 / R3 buttons correspond to the PS1 DualShock .
* Also used as id values for RETRO_DEVICE_INDEX_ANALOG_BUTTON */
2024-03-04 11:41:01 -05:00
# define RETRO_DEVICE_ID_JOYPAD_B 0
# define RETRO_DEVICE_ID_JOYPAD_Y 1
# define RETRO_DEVICE_ID_JOYPAD_SELECT 2
# define RETRO_DEVICE_ID_JOYPAD_START 3
# define RETRO_DEVICE_ID_JOYPAD_UP 4
# define RETRO_DEVICE_ID_JOYPAD_DOWN 5
# define RETRO_DEVICE_ID_JOYPAD_LEFT 6
# define RETRO_DEVICE_ID_JOYPAD_RIGHT 7
# define RETRO_DEVICE_ID_JOYPAD_A 8
# define RETRO_DEVICE_ID_JOYPAD_X 9
# define RETRO_DEVICE_ID_JOYPAD_L 10
# define RETRO_DEVICE_ID_JOYPAD_R 11
# define RETRO_DEVICE_ID_JOYPAD_L2 12
# define RETRO_DEVICE_ID_JOYPAD_R2 13
# define RETRO_DEVICE_ID_JOYPAD_L3 14
# define RETRO_DEVICE_ID_JOYPAD_R3 15
# define RETRO_DEVICE_ID_JOYPAD_MASK 256
2019-07-03 17:36:41 +01:00
2019-12-31 21:02:35 +01:00
/* Index / Id values for ANALOG device. */
2024-03-04 11:41:01 -05:00
# 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
2019-12-31 21:02:35 +01:00
/* Id values for MOUSE. */
2024-03-04 11:41:01 -05:00
# 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
2019-12-31 21:02:35 +01:00
/* Id values for LIGHTGUN. */
2024-03-04 11:41:01 -05:00
# 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
2019-12-31 21:02:35 +01:00
/* deprecated */
2024-03-04 11:41:01 -05:00
# 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*/
2019-12-31 21:02:35 +01:00
/* Id values for POINTER. */
2024-03-04 11:41:01 -05:00
# 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
2019-12-31 21:02:35 +01:00
/* Returned from retro_get_region(). */
2024-03-04 11:41:01 -05:00
# define RETRO_REGION_NTSC 0
# define RETRO_REGION_PAL 1
/* Id values for 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_LAST ,
/* Ensure sizeof(enum) == sizeof(int) */
RETRO_LANGUAGE_DUMMY = INT_MAX
} ;
2019-12-31 21:02:35 +01:00
/* Passed to retro_get_memory_data/size().
* If the memory type doesn ' t apply to the
* implementation NULL / 0 can be returned .
*/
2024-03-04 11:41:01 -05:00
# define RETRO_MEMORY_MASK 0xff
2019-12-31 21:02:35 +01:00
/* 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 . */
2024-03-04 11:41:01 -05:00
# define RETRO_MEMORY_SAVE_RAM 0
2019-12-31 21:02:35 +01:00
/* 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 .
*/
2024-03-04 11:41:01 -05:00
# define RETRO_MEMORY_RTC 1
2019-12-31 21:02:35 +01:00
/* System ram lets a frontend peek into a game systems main RAM. */
2024-03-04 11:41:01 -05:00
# define RETRO_MEMORY_SYSTEM_RAM 2
2019-12-31 21:02:35 +01:00
/* Video ram lets a frontend peek into a game systems video RAM (VRAM). */
2024-03-04 11:41:01 -05:00
# 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_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) */
} ;
2019-12-31 21:02:35 +01:00
/* If set, this call is not part of the public libretro API yet. It can
* change or be removed at any time . */
# define RETRO_ENVIRONMENT_EXPERIMENTAL 0x10000
/* Environment callback to be used internally in frontend. */
# define RETRO_ENVIRONMENT_PRIVATE 0x20000
/* Environment commands. */
2024-03-04 11:41:01 -05:00
# define RETRO_ENVIRONMENT_SET_ROTATION 1 / * const unsigned * --
* Sets screen rotation of graphics .
* Valid values are 0 , 1 , 2 , 3 , which rotates screen by 0 , 90 , 180 ,
* 270 degrees counter - clockwise respectively .
*/
# define RETRO_ENVIRONMENT_GET_OVERSCAN 2 / * bool * --
* NOTE : As of 2019 this callback is considered deprecated in favor of
* using core options to manage overscan in a more nuanced , core - specific way .
*
* Boolean value whether or not the implementation should use overscan ,
* or crop away overscan .
*/
# define RETRO_ENVIRONMENT_GET_CAN_DUPE 3 / * bool * --
* Boolean value whether or not frontend supports frame duping ,
* passing NULL to video frame callback .
*/
/* Environ 4, 5 are no longer supported (GET_VARIABLE / SET_VARIABLES),
2019-12-31 21:02:35 +01:00
* and reserved to avoid possible ABI clash .
*/
2024-03-04 11:41:01 -05:00
# define RETRO_ENVIRONMENT_SET_MESSAGE 6 / * const struct retro_message * --
* Sets a message to be displayed in implementation - specific manner
* for a certain amount of ' frames ' .
* Should not be used for trivial messages , which should simply be
* logged via RETRO_ENVIRONMENT_GET_LOG_INTERFACE ( or as a
* fallback , stderr ) .
*/
# define RETRO_ENVIRONMENT_SHUTDOWN 7 / * N / A (NULL) --
* Requests the frontend to shutdown .
* Should only be used if game has a specific
* way to shutdown the game from a menu item or similar .
*/
2019-12-31 21:02:35 +01:00
# define RETRO_ENVIRONMENT_SET_PERFORMANCE_LEVEL 8
2024-03-04 11:41:01 -05:00
/* const unsigned * --
2019-12-31 21:02:35 +01:00
* Gives a hint to the frontend how demanding this implementation
* is on a system . E . g . reporting a level of 2 means
* this implementation should run decently on all frontends
* of level 2 and up .
*
* 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 certain games an implementation can play might be
* particularly demanding .
* If called , it should be called in retro_load_game ( ) .
*/
# define RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY 9
2024-03-04 11:41:01 -05:00
/* const char ** --
2019-12-31 21:02:35 +01:00
* Returns the " system " directory of the frontend .
* This directory can be used to store system specific
* content such as BIOSes , configuration data , etc .
* The returned value can be NULL .
* If so , no such directory is defined ,
* and it ' s up to the implementation to find a suitable directory .
*
* NOTE : Some cores used this folder also for " save " data such as
* memory cards , etc , for lack of a better place to put it .
* This is now discouraged , and if possible , cores should try to
* use the new GET_SAVE_DIRECTORY .
*/
# define RETRO_ENVIRONMENT_SET_PIXEL_FORMAT 10
2024-03-04 11:41:01 -05:00
/* const enum retro_pixel_format * --
2019-12-31 21:02:35 +01:00
* Sets the internal pixel format used by the implementation .
* The default pixel format is RETRO_PIXEL_FORMAT_0RGB1555 .
* This pixel format however , is deprecated ( see enum retro_pixel_format ) .
* If the call returns false , the frontend does not support this pixel
* format .
*
* This function should be called inside retro_load_game ( ) or
* retro_get_system_av_info ( ) .
*/
# define RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS 11
2024-03-04 11:41:01 -05:00
/* const struct retro_input_descriptor * --
2019-12-31 21:02:35 +01:00
* Sets an array of retro_input_descriptors .
* It is up to the frontend to present this in a usable way .
* The array is terminated by retro_input_descriptor : : description
* being set to NULL .
* This function can be called at any time , but it is recommended
* to call it as early as possible .
*/
# define RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK 12
2024-03-04 11:41:01 -05:00
/* const struct retro_keyboard_callback * --
2019-12-31 21:02:35 +01:00
* Sets a callback function used to notify core about keyboard events .
*/
# define RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE 13
2024-03-04 11:41:01 -05:00
/* const struct retro_disk_control_callback * --
2019-12-31 21:02:35 +01:00
* Sets an interface which frontend can use to eject and insert
* disk images .
* This is used for games which consist of multiple images and
* must be manually swapped out by the user ( e . g . PSX ) .
*/
# define RETRO_ENVIRONMENT_SET_HW_RENDER 14
2024-03-04 11:41:01 -05:00
/* struct retro_hw_render_callback * --
2019-12-31 21:02:35 +01:00
* Sets an interface to let a libretro core render with
* hardware acceleration .
* Should be called in retro_load_game ( ) .
* If successful , libretro cores will be able to render to a
* frontend - provided framebuffer .
* The size of this framebuffer will be at least as large as
* max_width / max_height provided in get_av_info ( ) .
* If HW rendering is used , pass only RETRO_HW_FRAME_BUFFER_VALID or
* NULL to retro_video_refresh_t .
*/
# define RETRO_ENVIRONMENT_GET_VARIABLE 15
2024-03-04 11:41:01 -05:00
/* struct retro_variable * --
2019-12-31 21:02:35 +01:00
* Interface to acquire user - defined information from environment
* that cannot feasibly be supported in a multi - system way .
* ' key ' should be set to a key which has already been set by
* SET_VARIABLES .
* ' data ' will be set to a value or NULL .
*/
# define RETRO_ENVIRONMENT_SET_VARIABLES 16
2024-03-04 11:41:01 -05:00
/* const struct retro_variable * --
2019-12-31 21:02:35 +01:00
* Allows an implementation to signal the environment
* which variables it might want to check for later using
* GET_VARIABLE .
* This allows the frontend to present these variables to
* a user dynamically .
* This should be called the first time as early as
* possible ( ideally in retro_set_environment ) .
* Afterward it may be called again for the core to communicate
* updated options to the frontend , but the number of core
* options must not change from the number in the initial call .
2024-03-04 11:41:01 -05:00
*
2019-12-31 21:02:35 +01:00
* ' data ' points to an array of retro_variable structs
* terminated by a { NULL , NULL } element .
* retro_variable : : key should be namespaced to not collide
* with other implementations ' keys . E . g . A core called
* ' foo ' should use keys named as ' foo_option ' .
* retro_variable : : value should contain a human readable
* description of the key as well as a ' | ' delimited list
* of expected values .
*
* The number of possible options should be very limited ,
* i . e . it should be feasible to cycle through options
* without a keyboard .
*
* First entry should be treated as a default .
*
* Example entry :
* { " foo_option " , " Speed hack coprocessor X; false|true " }
*
* Text before first ' ; ' is description . This ' ; ' must be
* followed by a space , and followed by a list of possible
* values split up with ' | ' .
*
* Only strings are operated on . The possible values will
* generally be displayed and stored as - is by the frontend .
*/
# define RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE 17
2024-03-04 11:41:01 -05:00
/* bool * --
2019-12-31 21:02:35 +01:00
* Result is set to true if some variables are updated by
* frontend since last call to RETRO_ENVIRONMENT_GET_VARIABLE .
* Variables should be queried with GET_VARIABLE .
*/
# define RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME 18
2024-03-04 11:41:01 -05:00
/* const bool * --
2019-12-31 21:02:35 +01:00
* If true , the libretro implementation supports calls to
* retro_load_game ( ) with NULL as argument .
* Used by cores which can run without particular game data .
* This should be called within retro_set_environment ( ) only .
*/
# define RETRO_ENVIRONMENT_GET_LIBRETRO_PATH 19
2024-03-04 11:41:01 -05:00
/* const char ** --
2019-12-31 21:02:35 +01:00
* Retrieves the absolute path from where this libretro
* implementation was loaded .
* NULL is returned if the libretro was loaded statically
* ( i . e . linked statically to frontend ) , or if the path cannot be
* determined .
* Mostly useful in cooperation with SET_SUPPORT_NO_GAME as assets can
* be loaded without ugly hacks .
*/
2024-03-04 11:41:01 -05:00
/* Environment 20 was an obsolete version of SET_AUDIO_CALLBACK.
2019-12-31 21:02:35 +01:00
* It was not used by any known core at the time ,
* and was removed from the API . */
# define RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK 21
2024-03-04 11:41:01 -05:00
/* const struct retro_frame_time_callback * --
2019-12-31 21:02:35 +01:00
* Lets the core know how much time has passed since last
* invocation of retro_run ( ) .
* The frontend can tamper with the timing to fake fast - forward ,
* slow - motion , frame stepping , etc .
* In this case the delta time will use the reference value
* in frame_time_callback . .
*/
# define RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK 22
2024-03-04 11:41:01 -05:00
/* const struct retro_audio_callback * --
2019-12-31 21:02:35 +01:00
* Sets an interface which is used to notify a libretro core about audio
* being available for writing .
* The callback can be called from any thread , so a core using this must
* have a thread safe audio implementation .
* It is intended for games where audio and video are completely
* asynchronous and audio can be generated on the fly .
* This interface is not recommended for use with emulators which have
* highly synchronous audio .
*
* 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 implementation .
* Generally , the audio callback will be called continously in a loop .
*
* Due to thread safety guarantees and lack of sync between audio and
* video , a frontend can selectively disallow this interface based on
* internal configuration . A core using this interface must also
* implement the " normal " audio interface .
*
* A libretro core using SET_AUDIO_CALLBACK should also make use of
* SET_FRAME_TIME_CALLBACK .
*/
# define RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE 23
2024-03-04 11:41:01 -05:00
/* struct retro_rumble_interface * --
2019-12-31 21:02:35 +01:00
* Gets an interface which is used by a libretro core to set
* state of rumble motors in controllers .
* A strong and weak motor is supported , and they can be
* controlled indepedently .
2024-03-04 11:41:01 -05:00
* Should be called from either retro_init ( ) or retro_load_game ( ) .
* Should not be called from retro_set_environment ( ) .
* Returns false if rumble functionality is unavailable .
2019-12-31 21:02:35 +01:00
*/
# define RETRO_ENVIRONMENT_GET_INPUT_DEVICE_CAPABILITIES 24
2024-03-04 11:41:01 -05:00
/* uint64_t * --
2019-12-31 21:02:35 +01:00
* Gets a bitmask telling which device type are expected to be
* handled properly in a call to retro_input_state_t .
* Devices which are not handled or recognized always return
* 0 in retro_input_state_t .
* Example bitmask : caps = ( 1 < < RETRO_DEVICE_JOYPAD ) | ( 1 < < RETRO_DEVICE_ANALOG ) .
* Should only be called in retro_run ( ) .
*/
# define RETRO_ENVIRONMENT_GET_SENSOR_INTERFACE (25 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* struct retro_sensor_interface * --
2019-12-31 21:02:35 +01:00
* Gets access to the sensor interface .
* The purpose of this interface is to allow
* setting state related to sensors such as polling rate ,
* enabling / disable it entirely , etc .
* Reading sensor state is done via the normal
* input_state_callback API .
*/
# define RETRO_ENVIRONMENT_GET_CAMERA_INTERFACE (26 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* struct retro_camera_callback * --
2019-12-31 21:02:35 +01:00
* Gets an interface to a video camera driver .
* A libretro core can use this interface to get access to a
* video camera .
* New video frames are delivered in a callback in same
* thread as retro_run ( ) .
*
* GET_CAMERA_INTERFACE should be called in retro_load_game ( ) .
*
* Depending on the camera implementation used , camera frames
* will be delivered as a raw framebuffer ,
* or as an OpenGL texture directly .
*
* The core has to tell the frontend here which types of
* buffers can be handled properly .
* An OpenGL texture can only be handled when using a
* libretro GL core ( SET_HW_RENDER ) .
* It is recommended to use a libretro GL core when
* using camera interface .
*
* The camera is not started automatically . The retrieved start / stop
* functions must be used to explicitly
* start and stop the camera driver .
*/
# define RETRO_ENVIRONMENT_GET_LOG_INTERFACE 27
2024-03-04 11:41:01 -05:00
/* struct retro_log_callback * --
2019-12-31 21:02:35 +01:00
* Gets an interface for logging . This is useful for
* logging in a cross - platform way
* as certain platforms cannot use stderr for logging .
* It also allows the frontend to
* show logging information in a more suitable way .
* If this interface is not used , libretro cores should
* log to stderr as desired .
*/
# define RETRO_ENVIRONMENT_GET_PERF_INTERFACE 28
2024-03-04 11:41:01 -05:00
/* struct retro_perf_callback * --
2019-12-31 21:02:35 +01:00
* Gets an interface for performance counters . This is useful
* for performance logging in a cross - platform way and for detecting
* architecture - specific features , such as SIMD support .
*/
# define RETRO_ENVIRONMENT_GET_LOCATION_INTERFACE 29
2024-03-04 11:41:01 -05:00
/* struct retro_location_callback * --
2019-12-31 21:02:35 +01:00
* Gets access to the location interface .
* The purpose of this interface is to be able to retrieve
* location - based information from the host device ,
* such as current latitude / longitude .
*/
# define RETRO_ENVIRONMENT_GET_CONTENT_DIRECTORY 30 /* Old name, kept for compatibility. */
# define RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY 30
2024-03-04 11:41:01 -05:00
/* const char ** --
2019-12-31 21:02:35 +01:00
* Returns the " core assets " directory of the frontend .
* This directory can be used to store specific assets that the
* core relies upon , such as art assets ,
* input data , etc etc .
* The returned value can be NULL .
* If so , no such directory is defined ,
* and it ' s up to the implementation to find a suitable directory .
*/
# define RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY 31
2024-03-04 11:41:01 -05:00
/* const char ** --
2019-12-31 21:02:35 +01:00
* Returns the " save " directory of the frontend , unless there is no
* save directory available . The save directory should be used to
* store SRAM , memory cards , high scores , etc , if the libretro core
* cannot use the regular memory interface ( retro_get_memory_data ( ) ) .
*
* If the frontend cannot designate a save directory , it will return
* NULL to indicate that the core should attempt to operate without a
* save directory set .
*
* NOTE : early libretro cores used the system directory for save
* files . Cores that need to be backwards - compatible can still check
* GET_SYSTEM_DIRECTORY .
*/
# define RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO 32
2024-03-04 11:41:01 -05:00
/* const struct retro_system_av_info * --
2019-12-31 21:02:35 +01:00
* Sets a new av_info structure . This can only be called from
* within retro_run ( ) .
* This should * only * be used if the core is completely altering the
* internal resolutions , aspect ratios , timings , sampling rate , etc .
* Calling this can require a full reinitialization of video / audio
* drivers in the frontend ,
*
* so it is important to call it very sparingly , and usually only with
* the users explicit consent .
* An eventual driver reinitialize will happen so that video and
* audio callbacks
* happening after this call within the same retro_run ( ) call will
* target the newly initialized driver .
*
* This callback makes it possible to support configurable resolutions
* in games , which can be useful to
* avoid setting the " worst case " in max_width / max_height .
*
* * * * HIGHLY RECOMMENDED * * * Do not call this callback every time
* resolution changes in an emulator core if it ' s
* expected to be a temporary change , for the reasons of possible
* driver reinitialization .
* This call is not a free pass for not trying to provide
* correct values in retro_get_system_av_info ( ) . If you need to change
* things like aspect ratio or nominal width / height ,
* use RETRO_ENVIRONMENT_SET_GEOMETRY , which is a softer variant
* of SET_SYSTEM_AV_INFO .
*
* If this returns false , the frontend does not acknowledge a
* changed av_info struct .
*/
# define RETRO_ENVIRONMENT_SET_PROC_ADDRESS_CALLBACK 33
2024-03-04 11:41:01 -05:00
/* const struct retro_get_proc_address_interface * --
2019-12-31 21:02:35 +01:00
* Allows a libretro core to announce support for the
* get_proc_address ( ) interface .
* This interface allows for a standard way to extend libretro where
* use of environment calls are too indirect ,
* e . g . for cases where the frontend wants to call directly into the core .
*
* If a core wants to expose this interface , SET_PROC_ADDRESS_CALLBACK
* * * MUST * * be called from within retro_set_environment ( ) .
*/
# define RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO 34
2024-03-04 11:41:01 -05:00
/* const struct retro_subsystem_info * --
2019-12-31 21:02:35 +01:00
* This environment call introduces the concept of libretro " subsystems " .
* A subsystem is a variant of a libretro core which supports
* different kinds of games .
* The purpose of this is to support e . g . emulators which might
* have special needs , e . g . Super Nintendo ' s Super GameBoy , Sufami Turbo .
* It can also be used to pick among subsystems in an explicit way
* if the libretro implementation is a multi - system emulator itself .
*
* Loading a game via a subsystem is done with retro_load_game_special ( ) ,
* and this environment call allows a libretro core to expose which
* subsystems are supported for use with retro_load_game_special ( ) .
* A core passes an array of retro_game_special_info which is terminated
* with a zeroed out retro_game_special_info struct .
*
* If a core wants to use this functionality , SET_SUBSYSTEM_INFO
* * * MUST * * be called from within retro_set_environment ( ) .
*/
# define RETRO_ENVIRONMENT_SET_CONTROLLER_INFO 35
2024-03-04 11:41:01 -05:00
/* const struct retro_controller_info * --
2019-12-31 21:02:35 +01:00
* This environment call lets a libretro core tell the frontend
* which controller subclasses are recognized in calls to
* retro_set_controller_port_device ( ) .
*
* Some emulators such as Super Nintendo support multiple lightgun
* types which must be specifically selected from . It is therefore
* sometimes necessary for a frontend to be able to tell the core
* about a special kind of input device which is not specifcally
* provided by the Libretro API .
*
* In order for a frontend to understand the workings of those devices ,
* they must be defined as a specialized subclass of the generic device
* types already defined in the libretro API .
*
* The core must pass an array of const struct retro_controller_info which
* is terminated with a blanked out struct . Each element of the
* retro_controller_info struct corresponds to the ascending port index
* that is passed to retro_set_controller_port_device ( ) when that function
* is called to indicate to the core that the frontend has changed the
* active device subclass . SEE ALSO : retro_set_controller_port_device ( )
*
* The ascending input port indexes provided by the core in the struct
* are generally presented by frontends as ascending User # or Player # ,
* such as Player 1 , Player 2 , Player 3 , etc . Which device subclasses are
* supported can vary per input port .
*
* The first inner element of each entry in the retro_controller_info array
* is a retro_controller_description struct that specifies the names and
* codes of all device subclasses that are available for the corresponding
* User or Player , beginning with the generic Libretro device that the
* subclasses are derived from . The second inner element of each entry is the
* total number of subclasses that are listed in the retro_controller_description .
*
* NOTE : Even if special device types are set in the libretro core ,
* libretro should only poll input based on the base input device types .
*/
# define RETRO_ENVIRONMENT_SET_MEMORY_MAPS (36 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* const struct retro_memory_map * --
2019-12-31 21:02:35 +01:00
* This environment call lets a libretro core tell the frontend
* about the memory maps this core emulates .
* This can be used to implement , for example , cheats in a core - agnostic way .
*
* Should only be used by emulators ; it doesn ' t make much sense for
* anything else .
* It is recommended to expose all relevant pointers through
* retro_get_memory_ * as well .
*/
# define RETRO_ENVIRONMENT_SET_GEOMETRY 37
2024-03-04 11:41:01 -05:00
/* const struct retro_game_geometry * --
2019-12-31 21:02:35 +01:00
* This environment call is similar to SET_SYSTEM_AV_INFO for changing
* video parameters , but provides a guarantee that drivers will not be
* reinitialized .
* This can only be called from within retro_run ( ) .
*
* The purpose of this call is to allow a core to alter nominal
* width / heights as well as aspect ratios on - the - fly , which can be
* useful for some emulators to change in run - time .
*
* max_width / max_height arguments are ignored and cannot be changed
* with this call as this could potentially require a reinitialization or a
* non - constant time operation .
* If max_width / max_height are to be changed , SET_SYSTEM_AV_INFO is required .
*
* A frontend must guarantee that this environment call completes in
* constant time .
*/
# define RETRO_ENVIRONMENT_GET_USERNAME 38
2024-03-04 11:41:01 -05:00
/* const char **
2019-12-31 21:02:35 +01:00
* Returns the specified username of the frontend , if specified by the user .
* This username can be used as a nickname for a core that has online facilities
* or any other mode where personalization of the user is desirable .
* The returned value can be NULL .
* If this environ callback is used by a core that requires a valid username ,
* a default username should be specified by the core .
*/
# define RETRO_ENVIRONMENT_GET_LANGUAGE 39
2024-03-04 11:41:01 -05:00
/* unsigned * --
2019-12-31 21:02:35 +01:00
* Returns the specified language of the frontend , if specified by the user .
* It can be used by the core for localization purposes .
*/
# define RETRO_ENVIRONMENT_GET_CURRENT_SOFTWARE_FRAMEBUFFER (40 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* struct retro_framebuffer * --
2019-12-31 21:02:35 +01:00
* Returns a preallocated framebuffer which the core can use for rendering
* the frame into when not using SET_HW_RENDER .
* The framebuffer returned from this call must not be used
* after the current call to retro_run ( ) returns .
*
* The goal of this call is to allow zero - copy behavior where a core
* can render directly into video memory , avoiding extra bandwidth cost by copying
* memory from core to video memory .
*
* If this call succeeds and the core renders into it ,
* the framebuffer pointer and pitch can be passed to retro_video_refresh_t .
* If the buffer from GET_CURRENT_SOFTWARE_FRAMEBUFFER is to be used ,
* the core must pass the exact
* same pointer as returned by GET_CURRENT_SOFTWARE_FRAMEBUFFER ;
* i . e . passing a pointer which is offset from the
* buffer is undefined . The width , height and pitch parameters
* must also match exactly to the values obtained from GET_CURRENT_SOFTWARE_FRAMEBUFFER .
*
* It is possible for a frontend to return a different pixel format
* than the one used in SET_PIXEL_FORMAT . This can happen if the frontend
* needs to perform conversion .
*
* It is still valid for a core to render to a different buffer
* even if GET_CURRENT_SOFTWARE_FRAMEBUFFER succeeds .
*
* A frontend must make sure that the pointer obtained from this function is
* writeable ( and readable ) .
*/
# define RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE (41 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* const struct retro_hw_render_interface ** --
2019-12-31 21:02:35 +01:00
* Returns an API specific rendering interface for accessing API specific data .
* Not all HW rendering APIs support or need this .
* The contents of the returned pointer is specific to the rendering API
* being used . See the various headers like libretro_vulkan . h , etc .
*
* GET_HW_RENDER_INTERFACE cannot be called before context_reset has been called .
* Similarly , after context_destroyed callback returns ,
* the contents of the HW_RENDER_INTERFACE are invalidated .
*/
# define RETRO_ENVIRONMENT_SET_SUPPORT_ACHIEVEMENTS (42 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* const bool * --
2019-12-31 21:02:35 +01:00
* If true , the libretro implementation supports achievements
* either via memory descriptors set with RETRO_ENVIRONMENT_SET_MEMORY_MAPS
* or via retro_get_memory_data / retro_get_memory_size .
*
* This must be called before the first call to retro_run .
*/
# define RETRO_ENVIRONMENT_SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE (43 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* const struct retro_hw_render_context_negotiation_interface * --
2019-12-31 21:02:35 +01:00
* Sets an interface which lets the libretro core negotiate with frontend how a context is created .
* The semantics of this interface depends on which API is used in SET_HW_RENDER earlier .
* This interface will be used when the frontend is trying to create a HW rendering context ,
* so it will be used after SET_HW_RENDER , but before the context_reset callback .
*/
# define RETRO_ENVIRONMENT_SET_SERIALIZATION_QUIRKS 44
2024-03-04 11:41:01 -05:00
/* uint64_t * --
2019-12-31 21:02:35 +01:00
* Sets quirk flags associated with serialization . The frontend will zero any flags it doesn ' t
* recognize or support . Should be set in either retro_init or retro_load_game , but not both .
*/
# define RETRO_ENVIRONMENT_SET_HW_SHARED_CONTEXT (44 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* N/A (null) * --
2019-12-31 21:02:35 +01:00
* The frontend will try to use a ' shared ' hardware context ( mostly applicable
* to OpenGL ) when a hardware context is being set up .
*
* Returns true if the frontend supports shared hardware contexts and false
* if the frontend does not support shared hardware contexts .
*
* This will do nothing on its own until SET_HW_RENDER env callbacks are
* being used .
*/
# define RETRO_ENVIRONMENT_GET_VFS_INTERFACE (45 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* struct retro_vfs_interface_info * --
2019-12-31 21:02:35 +01:00
* Gets access to the VFS interface .
* VFS presence needs to be queried prior to load_game or any
* get_system / save / other_directory being called to let front end know
* core supports VFS before it starts handing out paths .
* It is recomended to do so in retro_set_environment
*/
# define RETRO_ENVIRONMENT_GET_LED_INTERFACE (46 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* struct retro_led_interface * --
2019-12-31 21:02:35 +01:00
* Gets an interface which is used by a libretro core to set
* state of LEDs .
*/
# define RETRO_ENVIRONMENT_GET_AUDIO_VIDEO_ENABLE (47 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* int * --
2019-12-31 21:02:35 +01:00
* Tells the core if the frontend wants audio or video .
* If disabled , the frontend will discard the audio or video ,
* so the core may decide to skip generating a frame or generating audio .
* This is mainly used for increasing performance .
* Bit 0 ( value 1 ) : Enable Video
* Bit 1 ( value 2 ) : Enable Audio
* Bit 2 ( value 4 ) : Use Fast Savestates .
* Bit 3 ( value 8 ) : Hard Disable Audio
* Other bits are reserved for future use and will default to zero .
* If video is disabled :
* * The frontend wants the core to not generate any video ,
* including presenting frames via hardware acceleration .
* * The frontend ' s video frame callback will do nothing .
* * 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 .
* If audio is disabled :
* * The frontend wants the core to not generate any audio .
* * The frontend ' s audio callbacks will do nothing .
* * 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 .
* Fast Savestates :
* * Guaranteed to be created by the same binary that will load them .
* * Will not be written to or read from the disk .
* * Suggest that the core assumes loading state will succeed .
* * Suggest that the core updates its memory buffers in - place if possible .
* * Suggest that the core skips clearing memory .
* * Suggest that the core skips resetting the system .
* * Suggest that the core may skip validation steps .
* Hard Disable Audio :
* * Used for a secondary core when running ahead .
* * Indicates that the frontend will never need audio from the core .
* * Suggests that the core may stop synthesizing audio , but this should not
* compromise 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 when using Hard Disable Audio .
*/
# define RETRO_ENVIRONMENT_GET_MIDI_INTERFACE (48 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* struct retro_midi_interface ** --
2019-12-31 21:02:35 +01:00
* Returns a MIDI interface that can be used for raw data I / O .
*/
# define RETRO_ENVIRONMENT_GET_FASTFORWARDING (49 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* bool * --
2019-12-31 21:02:35 +01:00
* Boolean value that indicates whether or not the frontend is in
* fastforwarding mode .
*/
# define RETRO_ENVIRONMENT_GET_TARGET_REFRESH_RATE (50 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* float * --
* Float value that lets us know what target refresh rate
2019-12-31 21:02:35 +01:00
* is curently in use by the frontend .
*
2024-03-04 11:41:01 -05:00
* The core can use the returned value to set an ideal
2019-12-31 21:02:35 +01:00
* refresh rate / framerate .
*/
2019-07-03 17:36:41 +01:00
# define RETRO_ENVIRONMENT_GET_INPUT_BITMASKS (51 | RETRO_ENVIRONMENT_EXPERIMENTAL)
2024-03-04 11:41:01 -05:00
/* bool * --
2019-07-03 17:36:41 +01:00
* Boolean value that indicates whether or not the frontend supports
* input bitmasks being returned by retro_input_state_t . The advantage
2024-03-04 11:41:01 -05:00
* of this is that retro_input_state_t has to be only called once to
2019-07-03 17:36:41 +01:00
* grab all button states instead of multiple times .
*
* If it returns true , you can pass RETRO_DEVICE_ID_JOYPAD_MASK as ' id '
* to retro_input_state_t ( make sure ' device ' is set to RETRO_DEVICE_JOYPAD ) .
* It will return a bitmask of all the digital buttons .
*/
2024-03-04 11:41:01 -05:00
# define RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION 52
/* unsigned * --
* Unsigned value is the API version number of the core options
* interface supported by the frontend . If callback return false ,
* API version is assumed to be 0.
*
* In legacy code , core options are set by passing an array of
* retro_variable structs to RETRO_ENVIRONMENT_SET_VARIABLES .
* This may be still be done regardless of the core options
* interface version .
*
* If version is > = 1 however , core options may instead be set by
* passing an array of retro_core_option_definition structs to
* RETRO_ENVIRONMENT_SET_CORE_OPTIONS , or a 2 D array of
* retro_core_option_definition structs to RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL .
* This allows the core to additionally set option sublabel information
* and / or provide localisation support .
*
* If version is > = 2 , core options may instead be set by passing
* a retro_core_options_v2 struct to RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 ,
* or an array of retro_core_options_v2 structs to
* RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL . This allows the core
* to additionally set optional core option category information
* for frontends with core option category support .
*/
# define RETRO_ENVIRONMENT_SET_CORE_OPTIONS 53
/* const struct retro_core_option_definition ** --
* Allows an implementation to signal the environment
* which variables it might want to check for later using
* GET_VARIABLE .
* This allows the frontend to present these variables to
* a user dynamically .
* This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION
* returns an API version of > = 1.
* This should be called instead of RETRO_ENVIRONMENT_SET_VARIABLES .
* This should be called the first time as early as
* possible ( ideally in retro_set_environment ) .
* Afterwards it may be called again for the core to communicate
* updated options to the frontend , but the number of core
* options must not change from the number in the initial call .
*
* ' data ' points to an array of retro_core_option_definition structs
* terminated by a { NULL , NULL , NULL , { { 0 } } , NULL } element .
* retro_core_option_definition : : key should be namespaced to not collide
* with other implementations ' keys . e . g . A core called
* ' foo ' should use keys named as ' foo_option ' .
* retro_core_option_definition : : desc should contain a human readable
* description of the key .
* retro_core_option_definition : : info should contain any additional human
* readable information text that a typical user may need to
* understand the functionality of the option .
* retro_core_option_definition : : values is an array of retro_core_option_value
* structs terminated by a { NULL , NULL } element .
* > retro_core_option_definition : : values [ index ] . value is an expected option
* value .
* > retro_core_option_definition : : values [ index ] . label is a human readable
* label used when displaying the value on screen . If NULL ,
* the value itself is used .
* retro_core_option_definition : : default_value is the default core option
* setting . It must match one of the expected option values in the
* retro_core_option_definition : : values array . If it does not , or the
* default value is NULL , the first entry in the
* retro_core_option_definition : : values array is treated as the default .
*
* The number of possible option values should be very limited ,
* and must be less than RETRO_NUM_CORE_OPTION_VALUES_MAX .
* i . e . it should be feasible to cycle through options
* without a keyboard .
*
* Example entry :
* {
* " 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 "
* }
*
* Only strings are operated on . The possible values will
* generally be displayed and stored as - is by the frontend .
*/
# define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL 54
/* const struct retro_core_options_intl * --
* Allows an implementation to signal the environment
* which variables it might want to check for later using
* GET_VARIABLE .
* This allows the frontend to present these variables to
* a user dynamically .
* This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION
* returns an API version of > = 1.
* This should be called instead of RETRO_ENVIRONMENT_SET_VARIABLES .
* This should be called instead of RETRO_ENVIRONMENT_SET_CORE_OPTIONS .
* This should be called the first time as early as
* possible ( ideally in retro_set_environment ) .
* Afterwards it may be called again for the core to communicate
* updated options to the frontend , but the number of core
* options must not change from the number in the initial call .
*
* This is fundamentally the same as RETRO_ENVIRONMENT_SET_CORE_OPTIONS ,
* with the addition of localisation support . The description of the
* RETRO_ENVIRONMENT_SET_CORE_OPTIONS callback should be consulted
* for further details .
*
* ' data ' points to a retro_core_options_intl struct .
*
* retro_core_options_intl : : us is a pointer to an array of
* retro_core_option_definition structs defining the US English
* core options implementation . It must point to a valid array .
*
* retro_core_options_intl : : local is a pointer to an array of
* retro_core_option_definition structs defining core options for
* the current frontend language . It may be NULL ( in which case
* retro_core_options_intl : : us is used by the frontend ) . Any items
* missing from this array will be read from retro_core_options_intl : : us
* instead .
*
* NOTE : Default core option values are always taken from the
* retro_core_options_intl : : us array . Any default values in
* retro_core_options_intl : : local array will be ignored .
*/
# define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY 55
/* struct retro_core_option_display * --
*
* Allows an implementation to signal the environment to show
* or hide a variable when displaying core options . This is
* considered a * suggestion * . The frontend is free to ignore
* this callback , and its implementation not considered mandatory .
*
* ' data ' points to a retro_core_option_display struct
*
* retro_core_option_display : : key is a variable identifier
* which has already been set by SET_VARIABLES / SET_CORE_OPTIONS .
*
* retro_core_option_display : : visible is a boolean , specifying
* whether variable should be displayed
*
* Note that all core option variables will be set visible by
* default when calling SET_VARIABLES / SET_CORE_OPTIONS .
*/
# define RETRO_ENVIRONMENT_GET_PREFERRED_HW_RENDER 56
/* unsigned * --
*
* Allows an implementation to ask frontend preferred hardware
* context to use . Core should use this information to deal
* with what specific context to request with SET_HW_RENDER .
*
* ' data ' points to an unsigned variable
*/
# define RETRO_ENVIRONMENT_GET_DISK_CONTROL_INTERFACE_VERSION 57
/* unsigned * --
* Unsigned value is the API version number of the disk control
* interface supported by the frontend . If callback return false ,
* API version is assumed to be 0.
*
* In legacy code , the disk control interface is defined by passing
* a struct of type retro_disk_control_callback to
* RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE .
* This may be still be done regardless of the disk control
* interface version .
*
* If version is > = 1 however , the disk control interface may
* instead be defined by passing a struct of type
* retro_disk_control_ext_callback to
* RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE .
* This allows the core to provide additional information about
* disk images to the frontend and / or enables extra
* disk control functionality by the frontend .
*/
# define RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE 58
/* const struct retro_disk_control_ext_callback * --
* Sets an interface which frontend can use to eject and insert
* disk images , and also obtain information about individual
* disk image files registered by the core .
* This is used for games which consist of multiple images and
* must be manually swapped out by the user ( e . g . PSX , floppy disk
* based systems ) .
*/
# define RETRO_ENVIRONMENT_GET_MESSAGE_INTERFACE_VERSION 59
/* unsigned * --
* Unsigned value is the API version number of the message
* interface supported by the frontend . If callback returns
* false , API version is assumed to be 0.
*
* In legacy code , messages may be displayed in an
* implementation - specific manner by passing a struct
* of type retro_message to RETRO_ENVIRONMENT_SET_MESSAGE .
* This may be still be done regardless of the message
* interface version .
*
* If version is > = 1 however , messages may instead be
* displayed by passing a struct of type retro_message_ext
* to RETRO_ENVIRONMENT_SET_MESSAGE_EXT . This allows the
* core to specify message logging level , priority and
* destination ( OSD , logging interface or both ) .
*/
# define RETRO_ENVIRONMENT_SET_MESSAGE_EXT 60
/* const struct retro_message_ext * --
* Sets a message to be displayed in an implementation - specific
* manner for a certain amount of ' frames ' . Additionally allows
* the core to specify message logging level , priority and
* destination ( OSD , logging interface or both ) .
* Should not be used for trivial messages , which should simply be
* logged via RETRO_ENVIRONMENT_GET_LOG_INTERFACE ( or as a
* fallback , stderr ) .
*/
# define RETRO_ENVIRONMENT_GET_INPUT_MAX_USERS 61
/* unsigned * --
* Unsigned value is the number of active input devices
* provided by the frontend . This may change between
* frames , but will remain constant for the duration
* of each frame .
* If callback returns true , a core need not poll any
* input device with an index greater than or equal to
* the number of active devices .
* If callback returns false , the number of active input
* devices is unknown . In this case , all input devices
* should be considered active .
*/
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
# define RETRO_ENVIRONMENT_SET_AUDIO_BUFFER_STATUS_CALLBACK 62
/* const struct retro_audio_buffer_status_callback * --
* Lets the core know the occupancy level of the frontend
* audio buffer . Can be used by a core to attempt frame
* skipping in order to avoid buffer under - runs .
* A core may pass NULL to disable buffer status reporting
* in the frontend .
*/
# define RETRO_ENVIRONMENT_SET_MINIMUM_AUDIO_LATENCY 63
/* const unsigned * --
* Sets minimum frontend audio latency in milliseconds .
* Resultant audio latency may be larger than set value ,
* or smaller if a hardware limit is encountered . A frontend
* is expected to honour requests up to 512 ms .
*
* - If value is less than current frontend
* audio latency , callback has no effect
* - If value is zero , default frontend audio
* latency is set
*
* May be used by a core to increase audio latency and
* therefore decrease the probability of buffer under - runs
* ( crackling ) when performing ' intensive ' operations .
* A core utilising RETRO_ENVIRONMENT_SET_AUDIO_BUFFER_STATUS_CALLBACK
* to implement audio - buffer - based frame skipping may achieve
* optimal results by setting the audio latency to a ' high '
* ( typically 6 x or 8 x ) integer multiple of the expected
* frame time .
*
* WARNING : This can only be called from within retro_run ( ) .
* Calling this can require a full reinitialization of audio
* drivers in the frontend , so it is important to call it very
* sparingly , and usually only with the users explicit consent .
* An eventual driver reinitialize will happen so that audio
* callbacks happening after this call within the same retro_run ( )
* call will target the newly initialized driver .
*/
# define RETRO_ENVIRONMENT_SET_FASTFORWARDING_OVERRIDE 64
/* const struct retro_fastforwarding_override * --
* Used by a libretro core to override the current
* fastforwarding mode of the frontend .
* If NULL is passed to this function , the frontend
* will return true if fastforwarding override
* functionality is supported ( no change in
* fastforwarding state will occur in this case ) .
*/
# 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 ( )
*/
# define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 67
/* const struct retro_core_options_v2 * --
* Allows an implementation to signal the environment
* which variables it might want to check for later using
* GET_VARIABLE .
* This allows the frontend to present these variables to
* a user dynamically .
* This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION
* returns an API version of > = 2.
* This should be called instead of RETRO_ENVIRONMENT_SET_VARIABLES .
* This should be called instead of RETRO_ENVIRONMENT_SET_CORE_OPTIONS .
* This should be called the first time as early as
* possible ( ideally in retro_set_environment ) .
* Afterwards it may be called again for the core to communicate
* updated options to the frontend , but the number of core
* options must not change from the number in the initial call .
* If RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION returns an API
* version of > = 2 , this callback is guaranteed to succeed
* ( i . e . callback return value does not indicate success )
* If callback returns true , frontend has core option category
* support .
* If callback returns false , frontend does not have core option
* category support .
*
* ' data ' points to a retro_core_options_v2 struct , containing
* of two pointers :
* - retro_core_options_v2 : : categories is an array of
* retro_core_option_v2_category structs terminated by a
* { NULL , NULL , NULL } element . If retro_core_options_v2 : : categories
* is NULL , all core options will have no category and will be shown
* at the top level of the frontend core option interface . If frontend
* does not have core option category support , categories array will
* be ignored .
* - retro_core_options_v2 : : definitions is an array of
* retro_core_option_v2_definition structs terminated by a
* { NULL , NULL , NULL , NULL , NULL , NULL , { { 0 } } , NULL }
* element .
*
* > > retro_core_option_v2_category notes :
*
* - retro_core_option_v2_category : : key should contain string
* that uniquely identifies the core option category . Valid
* key characters are [ a - z , A - Z , 0 - 9 , _ , - ]
* Namespace collisions with other implementations ' category
* keys are permitted .
* - retro_core_option_v2_category : : desc should contain a human
* readable description of the category key .
* - retro_core_option_v2_category : : info should contain any
* additional human readable information text that a typical
* user may need to understand the nature of the core option
* category .
*
* Example entry :
* {
* " advanced_settings " ,
* " Advanced " ,
* " Options affecting low-level emulation performance and accuracy. "
* }
*
* > > retro_core_option_v2_definition notes :
*
* - retro_core_option_v2_definition : : key should be namespaced to not
* collide with other implementations ' keys . e . g . A core called
* ' foo ' should use keys named as ' foo_option ' . Valid key characters
* are [ a - z , A - Z , 0 - 9 , _ , - ] .
* - retro_core_option_v2_definition : : desc should contain a human readable
* description of the key . Will be used when the frontend does not
* have core option category support . Examples : " Aspect Ratio " or
* " Video > Aspect Ratio " .
* - retro_core_option_v2_definition : : desc_categorized should contain a
* human readable description of the key , which will be used when
* frontend has core option category support . Example : " Aspect Ratio " ,
* where associated retro_core_option_v2_category : : desc is " Video " .
* If empty or NULL , the string specified by
* retro_core_option_v2_definition : : desc will be used instead .
* retro_core_option_v2_definition : : desc_categorized will be ignored
* if retro_core_option_v2_definition : : category_key is empty or NULL .
* - retro_core_option_v2_definition : : info should contain any additional
* human readable information text that a typical user may need to
* understand the functionality of the option .
* - retro_core_option_v2_definition : : info_categorized should contain
* any additional human readable information text that a typical user
* may need to understand the functionality of the option , and will be
* used when frontend has core option category support . This is provided
* to accommodate the case where info text references an option by
* name / desc , and the desc / desc_categorized text for that option differ .
* If empty or NULL , the string specified by
* retro_core_option_v2_definition : : info will be used instead .
* retro_core_option_v2_definition : : info_categorized will be ignored
* if retro_core_option_v2_definition : : category_key is empty or NULL .
* - retro_core_option_v2_definition : : category_key should contain a
* category identifier ( e . g . " video " or " audio " ) that will be
* assigned to the core option if frontend has core option category
* support . A categorized option will be shown in a subsection /
* submenu of the frontend core option interface . If key is empty
* or NULL , or if key does not match one of the
* retro_core_option_v2_category : : key values in the associated
* retro_core_option_v2_category array , option will have no category
* and will be shown at the top level of the frontend core option
* interface .
* - retro_core_option_v2_definition : : values is an array of
* retro_core_option_value structs terminated by a { NULL , NULL }
* element .
* - - > retro_core_option_v2_definition : : values [ index ] . value is an
* expected option value .
* - - > retro_core_option_v2_definition : : values [ index ] . label is a
* human readable label used when displaying the value on screen .
* If NULL , the value itself is used .
* - retro_core_option_v2_definition : : default_value is the default
* core option setting . It must match one of the expected option
* values in the retro_core_option_v2_definition : : values array . If
* it does not , or the default value is NULL , the first entry in the
* retro_core_option_v2_definition : : values array is treated as the
* default .
*
* The number of possible option values should be very limited ,
* and must be less than RETRO_NUM_CORE_OPTION_VALUES_MAX .
* i . e . it should be feasible to cycle through options
* without a keyboard .
*
* Example entries :
*
* - Uncategorized :
*
* {
* " foo_option " ,
* " Speed hack coprocessor X " ,
* NULL ,
* " Provides increased performance at the expense of reduced accuracy. " ,
* NULL ,
* NULL ,
* {
* { " false " , NULL } ,
* { " true " , NULL } ,
* { " unstable " , " Turbo (Unstable) " } ,
* { NULL , NULL } ,
* } ,
* " false "
* }
*
* - Categorized :
*
* {
* " foo_option " ,
* " Advanced > Speed hack coprocessor X " ,
* " Speed hack coprocessor X " ,
* " Setting 'Advanced > Speed hack coprocessor X' to 'true' or 'Turbo' provides increased performance at the expense of reduced accuracy " ,
* " Setting 'Speed hack coprocessor X' to 'true' or 'Turbo' provides increased performance at the expense of reduced accuracy " ,
* " advanced_settings " ,
* {
* { " false " , NULL } ,
* { " true " , NULL } ,
* { " unstable " , " Turbo (Unstable) " } ,
* { NULL , NULL } ,
* } ,
* " false "
* }
*
* Only strings are operated on . The possible values will
* generally be displayed and stored as - is by the frontend .
*/
# define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL 68
/* const struct retro_core_options_v2_intl * --
* Allows an implementation to signal the environment
* which variables it might want to check for later using
* GET_VARIABLE .
* This allows the frontend to present these variables to
* a user dynamically .
* This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION
* returns an API version of > = 2.
* This should be called instead of RETRO_ENVIRONMENT_SET_VARIABLES .
* This should be called instead of RETRO_ENVIRONMENT_SET_CORE_OPTIONS .
* This should be called instead of RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL .
* This should be called instead of RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 .
* This should be called the first time as early as
* possible ( ideally in retro_set_environment ) .
* Afterwards it may be called again for the core to communicate
* updated options to the frontend , but the number of core
* options must not change from the number in the initial call .
* If RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION returns an API
* version of > = 2 , this callback is guaranteed to succeed
* ( i . e . callback return value does not indicate success )
* If callback returns true , frontend has core option category
* support .
* If callback returns false , frontend does not have core option
* category support .
*
* This is fundamentally the same as RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 ,
* with the addition of localisation support . The description of the
* RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 callback should be consulted
* for further details .
*
* ' data ' points to a retro_core_options_v2_intl struct .
*
* - retro_core_options_v2_intl : : us is a pointer to a
* retro_core_options_v2 struct defining the US English
* core options implementation . It must point to a valid struct .
*
* - retro_core_options_v2_intl : : local is a pointer to a
* retro_core_options_v2 struct defining core options for
* the current frontend language . It may be NULL ( in which case
* retro_core_options_v2_intl : : us is used by the frontend ) . Any items
* missing from this struct will be read from
* retro_core_options_v2_intl : : us instead .
*
* NOTE : Default core option values are always taken from the
* retro_core_options_v2_intl : : us struct . Any default values in
* the retro_core_options_v2_intl : : local struct will be ignored .
*/
# define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_UPDATE_DISPLAY_CALLBACK 69
/* const struct retro_core_options_update_display_callback * --
* 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 ( ) .
*/
# define RETRO_ENVIRONMENT_SET_VARIABLE 70
/* const struct retro_variable * --
* Allows an implementation to notify the frontend
* that a core option value has changed .
*
* retro_variable : : key and retro_variable : : value
* must match strings that have been set previously
* via one of the following :
*
* - RETRO_ENVIRONMENT_SET_VARIABLES
* - RETRO_ENVIRONMENT_SET_CORE_OPTIONS
* - RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL
* - RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2
* - RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL
*
* After changing a core option value via this
* callback , RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE
* will return true .
*
* If data is NULL , no changes will be registered
* and the callback will return true ; an
* implementation may therefore pass NULL in order
* to test whether the callback is supported .
*/
# 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 ( ) .
*/
# define RETRO_ENVIRONMENT_GET_SAVESTATE_CONTEXT (72 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/* int * --
* Tells the core about the context the frontend is asking for savestate .
* ( see enum retro_savestate_context )
*/
# define RETRO_ENVIRONMENT_GET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_SUPPORT (73 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/* struct retro_hw_render_context_negotiation_interface * --
* Before calling SET_HW_RNEDER_CONTEXT_NEGOTIATION_INTERFACE , a core can query
* which version of the interface is supported .
*
* Frontend looks at interface_type and returns the maximum supported
* context negotiation interface version .
* If the interface_type is not supported or recognized by the frontend , a version of 0
* must be returned in interface_version and true is returned by frontend .
*
* If this environment call returns true with 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 .
*
* Backwards compatibility note :
* 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 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 .
*/
# define RETRO_ENVIRONMENT_GET_JIT_CAPABLE 74
/* bool * --
* Result is set to true if the frontend has already verified JIT can be
* used , mainly for use iOS / tvOS . On other platforms the result is true .
*/
# define RETRO_ENVIRONMENT_GET_MICROPHONE_INTERFACE (75 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/* struct retro_microphone_interface * --
* Returns an interface that can be used to receive input from the microphone driver .
*
* Returns true if microphone support is available ,
* even if no microphones are plugged in .
* Returns false if mic support is disabled or unavailable .
*
* This callback can be invoked at any time ,
* even before the microphone driver is ready .
*/
/* 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 . */
# define RETRO_ENVIRONMENT_GET_DEVICE_POWER (77 | RETRO_ENVIRONMENT_EXPERIMENTAL)
/* struct retro_device_power * --
* 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 NULL .
*
* If the frontend does not support this functionality ,
* then the provided argument will remain unchanged .
*
* Note that this environment call describes the power state for the entire device ,
* not for individual peripherals like controllers .
*/
# 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 .
*/
# define RETRO_ENVIRONMENT_GET_PLAYLIST_DIRECTORY 79
/* const char ** --
* 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 ) .
*
* The returned value can be NULL .
* If so , no such directory is defined ,
* and it ' s up to the implementation to find a suitable directory .
*/
/* VFS functionality */
/* File paths:
2019-07-03 17:36:41 +01:00
* File paths passed as parameters when using this API shall be well formed UNIX - style ,
2019-12-31 21:02:35 +01:00
* using " / " ( unquoted forward slash ) as directory separator regardless of the platform ' s native separator .
* Paths shall also include at least one forward slash ( " game.bin " is an invalid path , use " ./game.bin " instead ) .
* Other than the directory separator , cores shall not make assumptions about path format :
* " C:/path/game.bin " , " http://example.com/game.bin " , " #game/game.bin " , " ./game.bin " ( without quotes ) are all valid paths .
* 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 to front end .
* The frontend is encouraged to make such paths work as well as it can , but is allowed to give up if the core alters paths too much .
* Frontends are encouraged , but not required , to support native file system paths ( modulo replacing the directory separator , if applicable ) .
* Cores are allowed to try using them , but must remain functional if the front 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 support VFS . */
2024-03-04 11:41:01 -05:00
/* Opaque file handle
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
struct retro_vfs_file_handle ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Opaque directory handle
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v3 */
2024-03-04 11:41:01 -05:00
struct retro_vfs_dir_handle ;
2019-12-31 21:02:35 +01:00
/* File open flags
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
# define RETRO_VFS_FILE_ACCESS_READ (1 << 0) /* Read only mode */
# define RETRO_VFS_FILE_ACCESS_WRITE (1 << 1) /* Write only mode, discard contents and overwrites existing file unless RETRO_VFS_FILE_ACCESS_UPDATE is also specified */
# define RETRO_VFS_FILE_ACCESS_READ_WRITE (RETRO_VFS_FILE_ACCESS_READ | RETRO_VFS_FILE_ACCESS_WRITE) /* Read-write mode, discard contents and overwrites existing file unless RETRO_VFS_FILE_ACCESS_UPDATE is also specified*/
# define RETRO_VFS_FILE_ACCESS_UPDATE_EXISTING (1 << 2) /* Prevents discarding content of existing files opened for writing */
2019-12-31 21:02:35 +01:00
/* These are only hints. The frontend may choose to ignore them. Other than RAM/CPU/etc use,
and how they react to unlikely external interference ( for example someone else writing to that file ,
or the file ' s server going down ) , behavior will not change . */
2024-03-04 11:41:01 -05:00
# define RETRO_VFS_FILE_ACCESS_HINT_NONE (0)
2019-12-31 21:02:35 +01:00
/* Indicate that the file will be accessed many times. The frontend should aggressively cache everything. */
2024-03-04 11:41:01 -05:00
# define RETRO_VFS_FILE_ACCESS_HINT_FREQUENT_ACCESS (1 << 0)
2019-12-31 21:02:35 +01:00
/* Seek positions */
2024-03-04 11:41:01 -05:00
# define RETRO_VFS_SEEK_POSITION_START 0
# define RETRO_VFS_SEEK_POSITION_CURRENT 1
# define RETRO_VFS_SEEK_POSITION_END 2
2019-12-31 21:02:35 +01:00
/* stat() result flags
* Introduced in VFS API v3 */
2024-03-04 11:41:01 -05:00
# define RETRO_VFS_STAT_IS_VALID (1 << 0)
# define RETRO_VFS_STAT_IS_DIRECTORY (1 << 1)
# define RETRO_VFS_STAT_IS_CHARACTER_SPECIAL (1 << 2)
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Get path from opaque handle. Returns the exact same path passed to file_open when getting the handle
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
typedef const char * ( RETRO_CALLCONV * retro_vfs_get_path_t ) ( struct retro_vfs_file_handle * stream ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Open a file for reading or writing. If path points to a directory, this will
2019-12-31 21:02:35 +01:00
* fail . Returns the opaque file handle , or NULL for error .
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
typedef struct retro_vfs_file_handle * ( RETRO_CALLCONV * retro_vfs_open_t ) ( const char * path , unsigned mode , unsigned hints ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Close the file and release its resources. Must be called if open_file returns non-NULL. Returns 0 on success, -1 on failure.
2019-12-31 21:02:35 +01:00
* Whether the call succeeds ot not , the handle passed as parameter becomes invalid and should no longer be used .
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
typedef int ( RETRO_CALLCONV * retro_vfs_close_t ) ( struct retro_vfs_file_handle * stream ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Return the size of the file in bytes, or -1 for error.
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
typedef int64_t ( RETRO_CALLCONV * retro_vfs_size_t ) ( struct retro_vfs_file_handle * stream ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Truncate file to specified size. Returns 0 on success or -1 on error
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v2 */
2024-03-04 11:41:01 -05:00
typedef int64_t ( RETRO_CALLCONV * retro_vfs_truncate_t ) ( struct retro_vfs_file_handle * stream , int64_t length ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Get the current read / write position for the file. Returns -1 for error.
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
typedef int64_t ( RETRO_CALLCONV * retro_vfs_tell_t ) ( struct retro_vfs_file_handle * stream ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Set the current read/write position for the file. Returns the new position, -1 for error.
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
typedef int64_t ( RETRO_CALLCONV * retro_vfs_seek_t ) ( struct retro_vfs_file_handle * stream , int64_t offset , int seek_position ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Read data from a file. Returns the number of bytes read, or -1 for error.
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
typedef int64_t ( RETRO_CALLCONV * retro_vfs_read_t ) ( struct retro_vfs_file_handle * stream , void * s , uint64_t len ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Write data to a file. Returns the number of bytes written, or -1 for error.
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
typedef int64_t ( RETRO_CALLCONV * retro_vfs_write_t ) ( struct retro_vfs_file_handle * stream , const void * s , uint64_t len ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Flush pending writes to file, if using buffered IO. Returns 0 on sucess, or -1 on failure.
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
typedef int ( RETRO_CALLCONV * retro_vfs_flush_t ) ( struct retro_vfs_file_handle * stream ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Delete the specified file. Returns 0 on success, -1 on failure
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
typedef int ( RETRO_CALLCONV * retro_vfs_remove_t ) ( const char * path ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Rename the specified file. Returns 0 on success, -1 on failure
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
typedef int ( RETRO_CALLCONV * retro_vfs_rename_t ) ( const char * old_path , const char * new_path ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Stat the specified file. Retruns a bitmask of RETRO_VFS_STAT_* flags, none are set if path was not valid.
2019-12-31 21:02:35 +01:00
* Additionally stores file size in given variable , unless NULL is given .
* Introduced in VFS API v3 */
2024-03-04 11:41:01 -05:00
typedef int ( RETRO_CALLCONV * retro_vfs_stat_t ) ( const char * path , int32_t * size ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Create the specified directory. Returns 0 on success, -1 on unknown failure, -2 if already exists.
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v3 */
2024-03-04 11:41:01 -05:00
typedef int ( RETRO_CALLCONV * retro_vfs_mkdir_t ) ( const char * dir ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Open the specified directory for listing. Returns the opaque dir handle, or NULL for error.
2019-12-31 21:02:35 +01:00
* Support for the include_hidden argument may vary depending on the platform .
* Introduced in VFS API v3 */
2024-03-04 11:41:01 -05:00
typedef struct retro_vfs_dir_handle * ( RETRO_CALLCONV * retro_vfs_opendir_t ) ( const char * dir , bool include_hidden ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Read the directory entry at the current position, and move the read pointer to the next position.
2019-12-31 21:02:35 +01:00
* Returns true on success , false if already on the last entry .
* Introduced in VFS API v3 */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_vfs_readdir_t ) ( struct retro_vfs_dir_handle * dirstream ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Get the name of the last entry read. Returns a string on success, or NULL for error.
2019-12-31 21:02:35 +01:00
* The returned string pointer is valid until the next call to readdir or closedir .
* Introduced in VFS API v3 */
2024-03-04 11:41:01 -05:00
typedef const char * ( RETRO_CALLCONV * retro_vfs_dirent_get_name_t ) ( struct retro_vfs_dir_handle * dirstream ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Check if the last entry read was a directory. Returns true if it was, false otherwise (or on error).
2019-12-31 21:02:35 +01:00
* Introduced in VFS API v3 */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_vfs_dirent_is_dir_t ) ( struct retro_vfs_dir_handle * dirstream ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Close the directory and release its resources. Must be called if opendir returns non-NULL. Returns 0 on success, -1 on failure.
2019-12-31 21:02:35 +01:00
* Whether the call succeeds ot not , the handle passed as parameter becomes invalid and should no longer be used .
* Introduced in VFS API v3 */
2024-03-04 11:41:01 -05:00
typedef int ( RETRO_CALLCONV * retro_vfs_closedir_t ) ( struct retro_vfs_dir_handle * dirstream ) ;
struct retro_vfs_interface
{
/* VFS API v1 */
retro_vfs_get_path_t get_path ;
retro_vfs_open_t open ;
retro_vfs_close_t close ;
retro_vfs_size_t size ;
retro_vfs_tell_t tell ;
retro_vfs_seek_t seek ;
retro_vfs_read_t read ;
retro_vfs_write_t write ;
retro_vfs_flush_t flush ;
retro_vfs_remove_t remove ;
retro_vfs_rename_t rename ;
/* VFS API v2 */
retro_vfs_truncate_t truncate ;
/* VFS API v3 */
retro_vfs_stat_t stat ;
retro_vfs_mkdir_t mkdir ;
retro_vfs_opendir_t opendir ;
retro_vfs_readdir_t readdir ;
retro_vfs_dirent_get_name_t dirent_get_name ;
retro_vfs_dirent_is_dir_t dirent_is_dir ;
retro_vfs_closedir_t closedir ;
} ;
struct retro_vfs_interface_info
{
/* Set by core: should this be higher than the version the front end supports,
2019-12-31 21:02:35 +01:00
* front end will return false in the RETRO_ENVIRONMENT_GET_VFS_INTERFACE call
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
uint32_t required_interface_version ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Frontend writes interface pointer here. The frontend also sets the actual
2019-12-31 21:02:35 +01:00
* version , must be at least required_interface_version .
* Introduced in VFS API v1 */
2024-03-04 11:41:01 -05:00
struct retro_vfs_interface * iface ;
} ;
enum retro_hw_render_interface_type
{
RETRO_HW_RENDER_INTERFACE_VULKAN = 0 ,
RETRO_HW_RENDER_INTERFACE_D3D9 = 1 ,
RETRO_HW_RENDER_INTERFACE_D3D10 = 2 ,
RETRO_HW_RENDER_INTERFACE_D3D11 = 3 ,
RETRO_HW_RENDER_INTERFACE_D3D12 = 4 ,
RETRO_HW_RENDER_INTERFACE_GSKIT_PS2 = 5 ,
RETRO_HW_RENDER_INTERFACE_DUMMY = INT_MAX
} ;
/* Base struct. All retro_hw_render_interface_* types
2019-12-31 21:02:35 +01:00
* contain at least these fields . */
2024-03-04 11:41:01 -05:00
struct retro_hw_render_interface
{
enum retro_hw_render_interface_type interface_type ;
unsigned interface_version ;
} ;
typedef void ( RETRO_CALLCONV * retro_set_led_state_t ) ( int led , int state ) ;
struct retro_led_interface
{
retro_set_led_state_t set_led_state ;
} ;
/* Retrieves the current state of the MIDI input.
2019-12-31 21:02:35 +01:00
* Returns true if it ' s enabled , false otherwise . */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_midi_input_enabled_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Retrieves the current state of the MIDI output.
2019-12-31 21:02:35 +01:00
* Returns true if it ' s enabled , false otherwise */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_midi_output_enabled_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Reads next byte from the input stream.
2019-12-31 21:02:35 +01:00
* Returns true if byte is read , false otherwise . */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_midi_read_t ) ( uint8_t * byte ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Writes byte to the output stream.
2019-12-31 21:02:35 +01:00
* ' delta_time ' is in microseconds and represent time elapsed since previous write .
* Returns true if byte is written , false otherwise . */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_midi_write_t ) ( uint8_t byte , uint32_t delta_time ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Flushes previously written data.
2019-12-31 21:02:35 +01:00
* Returns true if successful , false otherwise . */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_midi_flush_t ) ( void ) ;
struct retro_midi_interface
{
retro_midi_input_enabled_t input_enabled ;
retro_midi_output_enabled_t output_enabled ;
retro_midi_read_t read ;
retro_midi_write_t write ;
retro_midi_flush_t flush ;
} ;
enum retro_hw_render_context_negotiation_interface_type
{
RETRO_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_VULKAN = 0 ,
RETRO_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_DUMMY = INT_MAX
} ;
/* Base struct. All retro_hw_render_context_negotiation_interface_* types
2019-12-31 21:02:35 +01:00
* contain at least these fields . */
2024-03-04 11:41:01 -05:00
struct retro_hw_render_context_negotiation_interface
{
enum retro_hw_render_context_negotiation_interface_type interface_type ;
unsigned interface_version ;
} ;
2019-12-31 21:02:35 +01:00
/* Serialized state is incomplete in some way. Set if serialization is
* usable in typical end - user cases but should not be relied upon to
* implement frame - sensitive frontend features such as netplay or
* rerecording . */
# define RETRO_SERIALIZATION_QUIRK_INCOMPLETE (1 << 0)
/* The core must spend some time initializing before serialization is
* supported . retro_serialize ( ) will initially fail ; retro_unserialize ( )
* and retro_serialize_size ( ) may or may not work correctly either . */
# define RETRO_SERIALIZATION_QUIRK_MUST_INITIALIZE (1 << 1)
/* 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)
2024-03-04 11:41:01 -05:00
# define RETRO_MEMDESC_CONST (1 << 0) /* The frontend will never change this memory area once retro_load_game has returned. */
# define RETRO_MEMDESC_BIGENDIAN (1 << 1) /* The memory area contains big endian data. Default is little endian. */
# define RETRO_MEMDESC_SYSTEM_RAM (1 << 2) /* The memory area is system RAM. This is main RAM of the gaming system. */
# define RETRO_MEMDESC_SAVE_RAM (1 << 3) /* The memory area is save RAM. This RAM is usually found on a game cartridge, backed up by a battery. */
# define RETRO_MEMDESC_VIDEO_RAM (1 << 4) /* The memory area is video RAM (VRAM) */
# define RETRO_MEMDESC_ALIGN_2 (1 << 16) /* All memory access in this area is aligned to their own size, or 2, whichever is smaller. */
# define RETRO_MEMDESC_ALIGN_4 (2 << 16)
# define RETRO_MEMDESC_ALIGN_8 (3 << 16)
# define RETRO_MEMDESC_MINSIZE_2 (1 << 24) /* All memory in this region is accessed at least 2 bytes at the time. */
# define RETRO_MEMDESC_MINSIZE_4 (2 << 24)
# define RETRO_MEMDESC_MINSIZE_8 (3 << 24)
struct retro_memory_descriptor
{
uint64_t flags ;
/* Pointer to the start of the relevant ROM or RAM chip.
2019-12-31 21:02:35 +01:00
* It ' s strongly recommended to use ' offset ' if possible , rather than
* doing math on the pointer .
*
* If the same byte is mapped my multiple descriptors , their descriptors
* must have the same pointer .
* If ' start ' does not point to the first byte in the pointer , put the
* difference in ' offset ' instead .
*
* May be NULL if there ' s nothing usable here ( e . g . hardware registers and
* open bus ) . No flags should be set if the pointer is NULL .
* It ' s recommended to minimize the number of descriptors if possible ,
* but not mandatory . */
2024-03-04 11:41:01 -05:00
void * ptr ;
size_t offset ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* This is the location in the emulated address space
2019-12-31 21:02:35 +01:00
* where the mapping starts . */
2024-03-04 11:41:01 -05:00
size_t start ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Which bits must be same as in 'start' for this mapping to apply.
2019-12-31 21:02:35 +01:00
* The first memory descriptor to claim a certain byte is the one
* that applies .
* A bit which is set in ' start ' must also be set in this .
* Can be zero , in which case each byte is assumed mapped exactly once .
* In this case , ' len ' must be a power of two . */
2024-03-04 11:41:01 -05:00
size_t select ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* If this is nonzero, the set bits are assumed not connected to the
2019-12-31 21:02:35 +01:00
* memory chip ' s address pins . */
2024-03-04 11:41:01 -05:00
size_t disconnect ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* This one tells the size of the current memory area.
2019-12-31 21:02:35 +01:00
* If , after start + disconnect are applied , the address is 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 infinite ( as limited
* by ' select ' and ' disconnect ' ) . */
2024-03-04 11:41:01 -05:00
size_t len ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* To go from emulated address to physical address, the following
2019-12-31 21:02:35 +01:00
* order applies :
* Subtract ' start ' , pick off ' disconnect ' , apply ' len ' , add ' offset ' . */
2024-03-04 11:41:01 -05:00
/* The address space name must consist of only a-zA-Z0-9_-,
2019-12-31 21:02:35 +01:00
* should be as short as feasible ( maximum length is 8 plus the NUL ) ,
* and may not be any other address space plus one or more 0 - 9 A - F
* at the end .
* However , multiple memory descriptors for the same address space is
* allowed , and the address space name can be empty . NULL is treated
* as empty .
*
* Address space names are case sensitive , but avoid lowercase if possible .
* The same pointer may exist in multiple address spaces .
*
* Examples :
* blank + blank - valid ( multiple things may be mapped in the same namespace )
* ' Sp ' + ' Sp ' - valid ( multiple things may be mapped in the same namespace )
* ' A ' + ' B ' - valid ( neither is a prefix of each other )
* ' S ' + blank - valid ( ' S ' is not in 0 - 9 A - F )
* ' a ' + blank - valid ( ' a ' is not in 0 - 9 A - F )
* ' a ' + ' A ' - valid ( neither is a prefix of each other )
* ' AR ' + blank - valid ( ' R ' is not in 0 - 9 A - F )
* ' ARB ' + blank - valid ( the B can ' t be part of the address either , because
* there is no namespace ' AR ' )
* blank + ' B ' - not valid , because it ' s ambigous which address space B1234
* would refer to .
* The length can ' t be used for that purpose ; the frontend may want
* to append arbitrary data to an address , without a separator . */
2024-03-04 11:41:01 -05:00
const char * addrspace ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* TODO: When finalizing this one, add a description field, which should be
2019-12-31 21:02:35 +01:00
* " WRAM " or something roughly equally long . */
2024-03-04 11:41:01 -05:00
/* TODO: When finalizing this one, replace 'select' with 'limit', which tells
2019-12-31 21:02:35 +01:00
* which bits can vary and still refer to the same address ( limit = ~ select ) .
* TODO : limit ? range ? vary ? something else ? */
2024-03-04 11:41:01 -05:00
/* TODO: When finalizing this one, if 'len' is above what 'select' (or
2019-12-31 21:02:35 +01:00
* ' 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 . */
2024-03-04 11:41:01 -05:00
/* TODO: When finalizing this one, fix the 'len' bit removal order.
2019-12-31 21:02:35 +01:00
* 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? */
2024-03-04 11:41:01 -05:00
/* TODO: Some emulators (MAME?) emulate big endian systems by only accessing
2019-12-31 21:02:35 +01:00
* 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 . */
2024-03-04 11:41:01 -05:00
/* TODO: Some of those flags are unused and/or don't really make sense. Clean
2019-12-31 21:02:35 +01:00
* them up . */
2024-03-04 11:41:01 -05:00
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* The frontend may use the largest value of 'start'+'select' in a
2019-12-31 21:02:35 +01:00
* certain namespace to infer the size of the address space .
*
* If the address space is larger than that , a mapping with . ptr = NULL
* should be at the end of the array , with . select set to all ones for
* as long as the address space is big .
*
* Sample descriptors ( minus . ptr , and RETRO_MEMFLAG_ on the flags ) :
* SNES WRAM :
* . start = 0x7E0000 , . len = 0x20000
* ( Note that this must be mapped before the ROM in most cases ; some of the
* ROM mappers
* try to claim $ 7E0000 , or at least $ 7E8000 . )
* SNES SPC700 RAM :
* . addrspace = " S " , . len = 0x10000
* SNES WRAM mirrors :
* . flags = MIRROR , . start = 0x000000 , . select = 0xC0E000 , . len = 0x2000
* . flags = MIRROR , . start = 0x800000 , . select = 0xC0E000 , . len = 0x2000
* SNES WRAM mirrors , alternate equivalent descriptor :
* . flags = MIRROR , . select = 0x40E000 , . disconnect = ~ 0x1FFF
* ( Various similar constructions can be created by combining parts of
* the above two . )
* SNES LoROM ( 512 KB , mirrored a couple of times ) :
* . flags = CONST , . start = 0x008000 , . select = 0x408000 , . disconnect = 0x8000 , . len = 512 * 1024
* . flags = CONST , . start = 0x400000 , . select = 0x400000 , . disconnect = 0x8000 , . len = 512 * 1024
* SNES HiROM ( 4 MB ) :
* . flags = CONST , . start = 0x400000 , . select = 0x400000 , . len = 4 * 1024 * 1024
* . flags = CONST , . offset = 0x8000 , . start = 0x008000 , . select = 0x408000 , . len = 4 * 1024 * 1024
* SNES ExHiROM ( 8 MB ) :
* . flags = CONST , . offset = 0 , . start = 0xC00000 , . select = 0xC00000 , . len = 4 * 1024 * 1024
* . flags = CONST , . offset = 4 * 1024 * 1024 , . start = 0x400000 , . select = 0xC00000 , . len = 4 * 1024 * 1024
* . flags = CONST , . offset = 0x8000 , . start = 0x808000 , . select = 0xC08000 , . len = 4 * 1024 * 1024
* . flags = CONST , . offset = 4 * 1024 * 1024 + 0x8000 , . start = 0x008000 , . select = 0xC08000 , . len = 4 * 1024 * 1024
* Clarify the size of the address space :
* . ptr = NULL , . select = 0xFFFFFF
* . len can be implied by . select in many of them , but was included for clarity .
*/
2024-03-04 11:41:01 -05:00
struct retro_memory_map
{
const struct retro_memory_descriptor * descriptors ;
unsigned num_descriptors ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_controller_description
{
/* Human-readable description of the controller. Even if using a generic
2019-12-31 21:02:35 +01:00
* input device type , this can be set to the particular device type the
* core uses . */
2024-03-04 11:41:01 -05:00
const char * desc ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Device type passed to retro_set_controller_port_device(). If the device
2019-12-31 21:02:35 +01:00
* type is a sub - class of a generic input device type , use the
* RETRO_DEVICE_SUBCLASS macro to create an ID .
*
* E . g . RETRO_DEVICE_SUBCLASS ( RETRO_DEVICE_JOYPAD , 1 ) . */
2024-03-04 11:41:01 -05:00
unsigned id ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_controller_info
{
const struct retro_controller_description * types ;
unsigned num_types ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_subsystem_memory_info
{
/* The extension associated with a memory type, e.g. "psram". */
const char * extension ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* The memory type for retro_get_memory(). This should be at
2019-12-31 21:02:35 +01:00
* least 0x100 to avoid conflict with standardized
* libretro memory types . */
2024-03-04 11:41:01 -05:00
unsigned type ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_subsystem_rom_info
{
/* Describes what the content is (SGB BIOS, GB ROM, etc). */
const char * desc ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Same definition as retro_get_system_info(). */
const char * valid_extensions ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Same definition as retro_get_system_info(). */
bool need_fullpath ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Same definition as retro_get_system_info(). */
bool block_extract ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* This is set if the content is required to load a game.
2019-12-31 21:02:35 +01:00
* If this is set to false , a zeroed - out retro_game_info can be passed . */
2024-03-04 11:41:01 -05:00
bool required ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Content can have multiple associated persistent
2019-12-31 21:02:35 +01:00
* memory types ( retro_get_memory ( ) ) . */
2024-03-04 11:41:01 -05:00
const struct retro_subsystem_memory_info * memory ;
unsigned num_memory ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_subsystem_info
{
/* Human-readable string of the subsystem type, e.g. "Super GameBoy" */
const char * desc ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* A computer friendly short string identifier for the subsystem type.
2019-12-31 21:02:35 +01:00
* This name must be [ a - z ] .
* E . g . if desc is " Super GameBoy " , this can be " sgb " .
* This identifier can be used for command - line interfaces , etc .
*/
2024-03-04 11:41:01 -05:00
const char * ident ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Infos for each content file. The first entry is assumed to be the
2019-12-31 21:02:35 +01:00
* " most significant " content for frontend purposes .
* 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 file paths based on the content used
* ( e . g . savestates ) , it should use the path for the first ROM to do so . */
2024-03-04 11:41:01 -05:00
const struct retro_subsystem_rom_info * roms ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Number of content files associated with a subsystem. */
unsigned num_roms ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* The type passed to retro_load_game_special(). */
unsigned id ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_proc_address_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* libretro API extension functions:
2019-12-31 21:02:35 +01:00
* ( None here so far ) .
*
* Get a symbol from a libretro core .
* Cores should only return symbols which are actual
* extensions to the libretro API .
*
* Frontends should not use this to obtain symbols to standard
* libretro entry points ( static linking or dlsym ) .
*
* The symbol name must be equal to the function name ,
* e . g . if void retro_foo ( void ) ; exists , the symbol must be called " retro_foo " .
* The returned function pointer must be cast to the corresponding type .
*/
2024-03-04 11:41:01 -05:00
typedef retro_proc_address_t ( RETRO_CALLCONV * retro_get_proc_address_t ) ( const char * sym ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_get_proc_address_interface
{
retro_get_proc_address_t get_proc_address ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
enum retro_log_level
{
RETRO_LOG_DEBUG = 0 ,
RETRO_LOG_INFO ,
RETRO_LOG_WARN ,
RETRO_LOG_ERROR ,
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
RETRO_LOG_DUMMY = INT_MAX
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Logging function. Takes log level argument as well. */
typedef void ( RETRO_CALLCONV * retro_log_printf_t ) ( enum retro_log_level level ,
const char * fmt , . . . ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_log_callback
{
retro_log_printf_t log ;
} ;
2019-12-31 21:02:35 +01:00
/* Performance related functions */
/* ID values for SIMD CPU features */
2024-03-04 11:41:01 -05:00
# define RETRO_SIMD_SSE (1 << 0)
# define RETRO_SIMD_SSE2 (1 << 1)
# define RETRO_SIMD_VMX (1 << 2)
# define RETRO_SIMD_VMX128 (1 << 3)
# define RETRO_SIMD_AVX (1 << 4)
# define RETRO_SIMD_NEON (1 << 5)
# define RETRO_SIMD_SSE3 (1 << 6)
# define RETRO_SIMD_SSSE3 (1 << 7)
# define RETRO_SIMD_MMX (1 << 8)
# define RETRO_SIMD_MMXEXT (1 << 9)
# define RETRO_SIMD_SSE4 (1 << 10)
# define RETRO_SIMD_SSE42 (1 << 11)
# define RETRO_SIMD_AVX2 (1 << 12)
# define RETRO_SIMD_VFPU (1 << 13)
# define RETRO_SIMD_PS (1 << 14)
# define RETRO_SIMD_AES (1 << 15)
# define RETRO_SIMD_VFPV3 (1 << 16)
# define RETRO_SIMD_VFPV4 (1 << 17)
# define RETRO_SIMD_POPCNT (1 << 18)
# define RETRO_SIMD_MOVBE (1 << 19)
# define RETRO_SIMD_CMOV (1 << 20)
# define RETRO_SIMD_ASIMD (1 << 21)
typedef uint64_t retro_perf_tick_t ;
typedef int64_t retro_time_t ;
struct retro_perf_counter
{
const char * ident ;
retro_perf_tick_t start ;
retro_perf_tick_t total ;
retro_perf_tick_t call_cnt ;
bool registered ;
} ;
/* Returns current time in microseconds.
2019-12-31 21:02:35 +01:00
* Tries to use the most accurate timer available .
*/
2024-03-04 11:41:01 -05:00
typedef retro_time_t ( RETRO_CALLCONV * retro_perf_get_time_usec_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* A simple counter. Usually nanoseconds, but can also be CPU cycles.
2019-12-31 21:02:35 +01:00
* Can be used directly if desired ( when creating a more sophisticated
* performance counter system ) .
* */
2024-03-04 11:41:01 -05:00
typedef retro_perf_tick_t ( RETRO_CALLCONV * retro_perf_get_counter_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Returns a bit-mask of detected CPU features (RETRO_SIMD_*). */
typedef uint64_t ( RETRO_CALLCONV * retro_get_cpu_features_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Asks frontend to log and/or display the state of performance counters.
2019-12-31 21:02:35 +01:00
* Performance counters can always be poked into manually as well .
*/
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_perf_log_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Register a performance counter.
2019-12-31 21:02:35 +01:00
* ident field must be set with a discrete value and other values in
* retro_perf_counter must be 0.
* Registering can be called multiple times . To avoid calling to
* frontend redundantly , you can check registered field first . */
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_perf_register_t ) ( struct retro_perf_counter * counter ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Starts a registered counter. */
typedef void ( RETRO_CALLCONV * retro_perf_start_t ) ( struct retro_perf_counter * counter ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Stops a registered counter. */
typedef void ( RETRO_CALLCONV * retro_perf_stop_t ) ( struct retro_perf_counter * counter ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* For convenience it can be useful to wrap register, start and stop in macros.
2019-12-31 21:02:35 +01:00
* E . g . :
* # ifdef LOG_PERFORMANCE
* # 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
* . . . Blank macros . . .
* # endif
*
* These can then be used mid - functions around code snippets .
*
* extern struct retro_perf_callback perf_cb ; * Somewhere in the core .
*
* void do_some_heavy_work ( void )
* {
* RETRO_PERFORMANCE_INIT ( cb , work_1 ;
* RETRO_PERFORMANCE_START ( cb , work_1 ) ;
* heavy_work_1 ( ) ;
* RETRO_PERFORMANCE_STOP ( cb , work_1 ) ;
*
* RETRO_PERFORMANCE_INIT ( cb , work_2 ) ;
* RETRO_PERFORMANCE_START ( cb , work_2 ) ;
* heavy_work_2 ( ) ;
* RETRO_PERFORMANCE_STOP ( cb , work_2 ) ;
* }
*
* void retro_deinit ( void )
* {
* perf_cb . perf_log ( ) ; * Log all perf counters here for example .
* }
*/
2024-03-04 11:41:01 -05:00
struct retro_perf_callback
{
retro_perf_get_time_usec_t get_time_usec ;
retro_get_cpu_features_t get_cpu_features ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
retro_perf_get_counter_t get_perf_counter ;
retro_perf_register_t perf_register ;
retro_perf_start_t perf_start ;
retro_perf_stop_t perf_stop ;
retro_perf_log_t perf_log ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* FIXME: Document the sensor API and work out behavior.
2019-12-31 21:02:35 +01:00
* It will be marked as experimental until then .
*/
2024-03-04 11:41:01 -05:00
enum retro_sensor_action
{
RETRO_SENSOR_ACCELEROMETER_ENABLE = 0 ,
RETRO_SENSOR_ACCELEROMETER_DISABLE ,
RETRO_SENSOR_GYROSCOPE_ENABLE ,
RETRO_SENSOR_GYROSCOPE_DISABLE ,
RETRO_SENSOR_ILLUMINANCE_ENABLE ,
RETRO_SENSOR_ILLUMINANCE_DISABLE ,
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
RETRO_SENSOR_DUMMY = INT_MAX
} ;
2019-12-31 21:02:35 +01:00
/* Id values for SENSOR types. */
# define RETRO_SENSOR_ACCELEROMETER_X 0
# define RETRO_SENSOR_ACCELEROMETER_Y 1
# define RETRO_SENSOR_ACCELEROMETER_Z 2
2024-03-04 11:41:01 -05:00
# define RETRO_SENSOR_GYROSCOPE_X 3
# define RETRO_SENSOR_GYROSCOPE_Y 4
# define RETRO_SENSOR_GYROSCOPE_Z 5
# define RETRO_SENSOR_ILLUMINANCE 6
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_set_sensor_state_t ) ( unsigned port ,
enum retro_sensor_action action , unsigned rate ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
typedef float ( RETRO_CALLCONV * retro_sensor_get_input_t ) ( unsigned port , unsigned id ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_sensor_interface
{
retro_set_sensor_state_t set_sensor_state ;
retro_sensor_get_input_t get_sensor_input ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
enum retro_camera_buffer
{
RETRO_CAMERA_BUFFER_OPENGL_TEXTURE = 0 ,
RETRO_CAMERA_BUFFER_RAW_FRAMEBUFFER ,
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
RETRO_CAMERA_BUFFER_DUMMY = INT_MAX
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Starts the camera driver. Can only be called in retro_run(). */
typedef bool ( RETRO_CALLCONV * retro_camera_start_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Stops the camera driver. Can only be called in retro_run(). */
typedef void ( RETRO_CALLCONV * retro_camera_stop_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Callback which signals when the camera driver is initialized
2019-12-31 21:02:35 +01:00
* and / or deinitialized .
* retro_camera_start_t can be called in initialized callback .
*/
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_camera_lifetime_status_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* A callback for raw framebuffer data. buffer points to an XRGB8888 buffer.
2019-12-31 21:02:35 +01:00
* Width , height and pitch are similar to retro_video_refresh_t .
* First pixel is top - left origin .
*/
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_camera_frame_raw_framebuffer_t ) ( const uint32_t * buffer ,
unsigned width , unsigned height , size_t pitch ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* A callback for when OpenGL textures are used.
2019-12-31 21:02:35 +01:00
*
* texture_id is a texture owned by camera driver .
* Its state or content should be considered immutable , except for things like
* texture filtering and clamping .
*
* texture_target is the texture target for the GL texture .
* These can include e . g . GL_TEXTURE_2D , GL_TEXTURE_RECTANGLE , and possibly
* more depending on extensions .
*
* affine points to a packed 3 x3 column - major matrix used to apply an affine
* transform to texture coordinates . ( affine_matrix * vec3 ( coord_x , coord_y , 1.0 ) )
* After transform , normalized texture coord ( 0 , 0 ) should be bottom - left
* and ( 1 , 1 ) should be top - right ( or ( width , height ) for RECTANGLE ) .
*
* GL - specific typedefs are avoided here to avoid relying on gl . h in
* the API definition .
*/
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_camera_frame_opengl_texture_t ) ( unsigned texture_id ,
unsigned texture_target , const float * affine ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_camera_callback
{
/* Set by libretro core.
2019-12-31 21:02:35 +01:00
* Example bitmask : caps = ( 1 < < RETRO_CAMERA_BUFFER_OPENGL_TEXTURE ) | ( 1 < < RETRO_CAMERA_BUFFER_RAW_FRAMEBUFFER ) .
*/
2024-03-04 11:41:01 -05:00
uint64_t caps ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Desired resolution for camera. Is only used as a hint. */
unsigned width ;
unsigned height ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Set by frontend. */
retro_camera_start_t start ;
retro_camera_stop_t stop ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Set by libretro core if raw framebuffer callbacks will be used. */
retro_camera_frame_raw_framebuffer_t frame_raw_framebuffer ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Set by libretro core if OpenGL texture callbacks will be used. */
retro_camera_frame_opengl_texture_t frame_opengl_texture ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Set by libretro core. Called after camera driver is initialized and
2019-12-31 21:02:35 +01:00
* ready to be started .
* Can be NULL , in which this callback is not called .
*/
2024-03-04 11:41:01 -05:00
retro_camera_lifetime_status_t initialized ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Set by libretro core. Called right before camera driver is
2019-12-31 21:02:35 +01:00
* deinitialized .
* Can be NULL , in which this callback is not called .
*/
2024-03-04 11:41:01 -05:00
retro_camera_lifetime_status_t deinitialized ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Sets the interval of time and/or distance at which to update/poll
2019-12-31 21:02:35 +01:00
* location - based data .
*
* To ensure compatibility with all location - based implementations ,
* values for both interval_ms and interval_distance should be provided .
*
* interval_ms is the interval expressed in milliseconds .
* interval_distance is the distance interval expressed in meters .
*/
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_location_set_interval_t ) ( unsigned interval_ms ,
unsigned interval_distance ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Start location services. The device will start listening for changes to the
2019-12-31 21:02:35 +01:00
* current location at regular intervals ( which are defined with
* retro_location_set_interval_t ) . */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_location_start_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Stop location services. The device will stop listening for changes
2019-12-31 21:02:35 +01:00
* to the current location . */
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_location_stop_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Get the position of the current location. Will set parameters to
2019-12-31 21:02:35 +01:00
* 0 if no new location update has happened since the last time . */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_location_get_position_t ) ( double * lat , double * lon ,
double * horiz_accuracy , double * vert_accuracy ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Callback which signals when the location driver is initialized
2019-12-31 21:02:35 +01:00
* and / or deinitialized .
* retro_location_start_t can be called in initialized callback .
*/
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_location_lifetime_status_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_location_callback
{
retro_location_start_t start ;
retro_location_stop_t stop ;
retro_location_get_position_t get_position ;
retro_location_set_interval_t set_interval ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
retro_location_lifetime_status_t initialized ;
retro_location_lifetime_status_t deinitialized ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
enum retro_rumble_effect
{
RETRO_RUMBLE_STRONG = 0 ,
RETRO_RUMBLE_WEAK = 1 ,
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
RETRO_RUMBLE_DUMMY = INT_MAX
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Sets rumble state for joypad plugged in port 'port'.
2019-12-31 21:02:35 +01:00
* Rumble effects are controlled independently ,
* and setting e . g . strong rumble does not override weak rumble .
* Strength has a range of [ 0 , 0xffff ] .
*
* Returns true if rumble state request was honored .
* Calling this before first retro_run ( ) is likely to return false . */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_set_rumble_state_t ) ( unsigned port ,
enum retro_rumble_effect effect , uint16_t strength ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_rumble_interface
{
retro_set_rumble_state_t set_rumble_state ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Notifies libretro that audio data should be written. */
typedef void ( RETRO_CALLCONV * retro_audio_callback_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* True: Audio driver in frontend is active, and callback is
2019-12-31 21:02:35 +01:00
* expected to be called regularily .
* False : Audio driver in frontend is paused or inactive .
* Audio callback will not be called until set_state has been
* called with true .
* Initial state is false ( inactive ) .
*/
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_audio_set_state_callback_t ) ( bool enabled ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_audio_callback
{
retro_audio_callback_t callback ;
retro_audio_set_state_callback_t set_state ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Notifies a libretro core of time spent since last invocation
2019-12-31 21:02:35 +01:00
* of retro_run ( ) in microseconds .
*
* It will be called right before retro_run ( ) every frame .
* The frontend can tamper with timing to support cases like
* fast - forward , slow - motion and framestepping .
*
* In those scenarios the reference frame time value will be used . */
2024-03-04 11:41:01 -05:00
typedef int64_t retro_usec_t ;
typedef void ( RETRO_CALLCONV * retro_frame_time_callback_t ) ( retro_usec_t usec ) ;
struct retro_frame_time_callback
{
retro_frame_time_callback_t callback ;
/* Represents the time of one frame. It is computed as
2019-12-31 21:02:35 +01:00
* 1000000 / fps , but the implementation will resolve the
* rounding to ensure that framestepping , etc is exact . */
2024-03-04 11:41:01 -05:00
retro_usec_t reference ;
} ;
/* Notifies a libretro core of the current occupancy
* level of the frontend audio buffer .
*
* - active : ' true ' if audio buffer is currently
* in use . Will be ' false ' if audio is
* disabled in the frontend
*
* - occupancy : Given as a value in the range [ 0 , 100 ] ,
* corresponding to the occupancy percentage
* of the audio buffer
*
* - underrun_likely : ' true ' if the frontend expects an
* audio buffer underrun during the
* next frame ( indicates that a core
* should attempt frame skipping )
*
* It will be called right before retro_run ( ) every frame . */
typedef void ( RETRO_CALLCONV * retro_audio_buffer_status_callback_t ) (
bool active , unsigned occupancy , bool underrun_likely ) ;
struct retro_audio_buffer_status_callback
{
retro_audio_buffer_status_callback_t callback ;
} ;
2019-12-31 21:02:35 +01:00
/* 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)
2024-03-04 11:41:01 -05:00
/* Invalidates the current HW context.
2019-12-31 21:02:35 +01:00
* 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 .
*/
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_hw_context_reset_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Gets current framebuffer which is to be rendered to.
2019-12-31 21:02:35 +01:00
* Could change every frame potentially .
*/
2024-03-04 11:41:01 -05:00
typedef uintptr_t ( RETRO_CALLCONV * retro_hw_get_current_framebuffer_t ) ( void ) ;
2019-06-25 19:04:04 +01:00
2024-03-04 11:41:01 -05:00
/* Get a symbol from HW context. */
typedef retro_proc_address_t ( RETRO_CALLCONV * retro_hw_get_proc_address_t ) ( const char * sym ) ;
2019-06-25 19:04:04 +01:00
2024-03-04 11:41:01 -05:00
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/
2019-12-31 21:02:35 +01:00
* version_minor fields to set GL version . */
2024-03-04 11:41:01 -05:00
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,
2019-12-31 21:02:35 +01:00
* use the corresponding enums directly . */
2024-03-04 11:41:01 -05:00
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 ,
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Direct3D10, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */
RETRO_HW_CONTEXT_D3D10 = 8 ,
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Direct3D12, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */
RETRO_HW_CONTEXT_D3D12 = 9 ,
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Direct3D9, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */
RETRO_HW_CONTEXT_D3D9 = 10 ,
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
RETRO_HW_CONTEXT_DUMMY = INT_MAX
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
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.
2019-12-31 21:02:35 +01:00
* 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 .
*/
2024-03-04 11:41:01 -05:00
retro_hw_context_reset_t context_reset ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Set by frontend.
2019-12-31 21:02:35 +01:00
* TODO : This is rather obsolete . The frontend should not
* be providing preallocated framebuffers . */
2024-03-04 11:41:01 -05:00
retro_hw_get_current_framebuffer_t get_current_framebuffer ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Set by frontend.
2019-12-31 21:02:35 +01:00
* Can return all relevant functions , including glClear on Windows . */
2024-03-04 11:41:01 -05:00
retro_hw_get_proc_address_t get_proc_address ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Set if render buffers should have depth component attached.
2019-12-31 21:02:35 +01:00
* TODO : Obsolete . */
2024-03-04 11:41:01 -05:00
bool depth ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Set if stencil buffers should be attached.
2019-12-31 21:02:35 +01:00
* TODO : Obsolete . */
2024-03-04 11:41:01 -05:00
bool stencil ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* If depth and stencil are true, a packed 24/8 buffer will be added.
2019-12-31 21:02:35 +01:00
* Only attaching stencil is invalid and will be ignored . */
2024-03-04 11:41:01 -05:00
/* Use conventional bottom-left origin convention. If false,
2019-12-31 21:02:35 +01:00
* standard libretro top - left origin semantics are used .
* TODO : Move to GL specific interface . */
2024-03-04 11:41:01 -05:00
bool bottom_left_origin ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Major version number for core GL context or GLES 3.1+. */
unsigned version_major ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Minor version number for core GL context or GLES 3.1+. */
unsigned version_minor ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* If this is true, the frontend will go very far to avoid
2019-12-31 21:02:35 +01:00
* resetting context in scenarios like toggling fullscreen , etc .
* TODO : Obsolete ? Maybe frontend should just always assume this . . .
*/
2024-03-04 11:41:01 -05:00
bool cache_context ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* The reset callback might still be called in extreme situations
2019-12-31 21:02:35 +01:00
* 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 .
*/
2024-03-04 11:41:01 -05:00
/* A callback to be called before the context is destroyed in a
2019-12-31 21:02:35 +01:00
* controlled way by the frontend . */
2024-03-04 11:41:01 -05:00
retro_hw_context_reset_t context_destroy ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* OpenGL resources can be deinitialized cleanly at this step.
2019-12-31 21:02:35 +01:00
* 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 .
*/
2024-03-04 11:41:01 -05:00
/* Creates a debug context. */
bool debug_context ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Callback type passed in RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK.
2019-12-31 21:02:35 +01:00
* Called by the frontend in response to keyboard events .
* down is set if the key is being pressed , or false if it is being released .
* keycode is the RETROK value of the char .
* character is the text character of the pressed key . ( UTF - 32 ) .
* key_modifiers is a set of RETROKMOD values or ' ed together .
*
* The pressed / keycode state can be indepedent of the character .
* It is also possible that multiple characters are generated from a
* single keypress .
* Keycode events should be treated separately from character events .
* However , when possible , the frontend should try to synchronize these .
* If only a character is posted , keycode should be RETROK_UNKNOWN .
*
* Similarily if only a keycode event is generated with no corresponding
* character , character should be 0.
*/
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_keyboard_event_t ) ( bool down , unsigned keycode ,
uint32_t character , uint16_t key_modifiers ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_keyboard_callback
{
retro_keyboard_event_t callback ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Callbacks for RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE &
* RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE .
2019-12-31 21:02:35 +01:00
* Should be set for implementations which can swap out multiple disk
* images in runtime .
*
* If the implementation can do this automatically , it should strive to do so .
* However , there are cases where the user must manually do so .
*
* Overview : To swap a disk image , eject the disk image with
* set_eject_state ( true ) .
* Set the disk index with set_image_index ( index ) . Insert the disk again
* with set_eject_state ( false ) .
*/
2024-03-04 11:41:01 -05:00
/* If ejected is true, "ejects" the virtual disk tray.
2019-12-31 21:02:35 +01:00
* When ejected , the disk image index can be set .
*/
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_set_eject_state_t ) ( bool ejected ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Gets current eject state. The initial state is 'not ejected'. */
typedef bool ( RETRO_CALLCONV * retro_get_eject_state_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Gets current disk index. First disk is index 0.
2019-12-31 21:02:35 +01:00
* If return value is > = get_num_images ( ) , no disk is currently inserted .
*/
2024-03-04 11:41:01 -05:00
typedef unsigned ( RETRO_CALLCONV * retro_get_image_index_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Sets image index. Can only be called when disk is ejected.
2019-12-31 21:02:35 +01:00
* The implementation supports setting " no disk " by using an
* index > = get_num_images ( ) .
*/
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_set_image_index_t ) ( unsigned index ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Gets total number of images which are available to use. */
typedef unsigned ( RETRO_CALLCONV * retro_get_num_images_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_game_info ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Replaces the disk image associated with index.
2019-12-31 21:02:35 +01:00
* Arguments to pass in info have same requirements as retro_load_game ( ) .
* Virtual disk tray must be ejected when calling this .
*
* Replacing a disk image with info = NULL will remove the disk image
* from the internal list .
* As a result , calls to get_image_index ( ) can change .
*
* E . g . replace_image_index ( 1 , NULL ) , and previous get_image_index ( )
* returned 4 before .
* Index 1 will be removed , and the new index is 3.
*/
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_replace_image_index_t ) ( unsigned index ,
const struct retro_game_info * info ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Adds a new valid index (get_num_images()) to the internal disk list.
2019-12-31 21:02:35 +01:00
* This will increment subsequent return values from get_num_images ( ) by 1.
* This image index cannot be used until a disk image has been set
* with replace_image_index . */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_add_image_index_t ) ( void ) ;
/* Sets initial image to insert in drive when calling
* core_load_game ( ) .
* Since we cannot pass the initial index when loading
* content ( this would require a major API change ) , this
* is set by the frontend * before * calling the core ' s
* retro_load_game ( ) / retro_load_game_special ( ) implementation .
* A core should therefore cache the index / path values and handle
* them inside retro_load_game ( ) / retro_load_game_special ( ) .
* - If ' index ' is invalid ( index > = get_num_images ( ) ) , the
* core should ignore the set value and instead use 0
* - ' path ' is used purely for error checking - i . e . when
* content is loaded , the core should verify that the
* disk specified by ' index ' has the specified file 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
* 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 set path and content path do not match , the core should
* ignore the set ' index ' value and instead use 0
* Returns ' false ' if index or ' path ' are invalid , or core
* does not support this functionality
*/
typedef bool ( RETRO_CALLCONV * retro_set_initial_image_t ) ( unsigned index , const char * path ) ;
/* Fetches the path of the specified disk image file.
* Returns ' false ' if index is invalid ( index > = get_num_images ( ) )
* or path is otherwise unavailable .
*/
typedef bool ( RETRO_CALLCONV * retro_get_image_path_t ) ( unsigned index , char * path , size_t len ) ;
/* Fetches a core-provided 'label' for the specified disk
* image file . In the simplest case this may be a file name
* ( without extension ) , but for cores with more complex
* content requirements information may be provided to
* facilitate user disk swapping - for example , a core
* running floppy - disk - based content may uniquely label
* save disks , data disks , level disks , etc . with names
* corresponding to in - game disk change prompts ( so the
* frontend can provide better user guidance than a ' dumb '
* disk index value ) .
* Returns ' false ' if index is invalid ( index > = get_num_images ( ) )
* or label is otherwise unavailable .
*/
typedef bool ( RETRO_CALLCONV * retro_get_image_label_t ) ( unsigned index , char * label , size_t len ) ;
struct retro_disk_control_callback
{
retro_set_eject_state_t set_eject_state ;
retro_get_eject_state_t get_eject_state ;
retro_get_image_index_t get_image_index ;
retro_set_image_index_t set_image_index ;
retro_get_num_images_t get_num_images ;
retro_replace_image_index_t replace_image_index ;
retro_add_image_index_t add_image_index ;
} ;
struct retro_disk_control_ext_callback
{
retro_set_eject_state_t set_eject_state ;
retro_get_eject_state_t get_eject_state ;
retro_get_image_index_t get_image_index ;
retro_set_image_index_t set_image_index ;
retro_get_num_images_t get_num_images ;
retro_replace_image_index_t replace_image_index ;
retro_add_image_index_t add_image_index ;
/* NOTE: Frontend will only attempt to record/restore
* last used disk index if both set_initial_image ( )
* and get_image_path ( ) are implemented */
retro_set_initial_image_t set_initial_image ; /* Optional - may be NULL */
retro_get_image_path_t get_image_path ; /* Optional - may be NULL */
retro_get_image_label_t get_image_label ; /* Optional - may be NULL */
} ;
/* 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 ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* 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 ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* 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 ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* 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 ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* 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 */
} ;
enum retro_pixel_format
{
/* 0RGB1555, native endian.
2019-12-31 21:02:35 +01:00
* 0 bit must be set to 0.
* This pixel format is default for compatibility concerns only .
* If a 15 / 16 - bit pixel format is desired , consider using RGB565 . */
2024-03-04 11:41:01 -05:00
RETRO_PIXEL_FORMAT_0RGB1555 = 0 ,
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* XRGB8888, native endian.
2019-12-31 21:02:35 +01:00
* X bits are ignored . */
2024-03-04 11:41:01 -05:00
RETRO_PIXEL_FORMAT_XRGB8888 = 1 ,
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* RGB565, native endian.
2019-12-31 21:02:35 +01:00
* This pixel format is the recommended format to use if a 15 / 16 - bit
* format is desired as it is the pixel format that is typically
* available on a wide range of low - power devices .
*
* It is also natively supported in APIs like OpenGL ES . */
2024-03-04 11:41:01 -05:00
RETRO_PIXEL_FORMAT_RGB565 = 2 ,
/* Ensure sizeof() == sizeof(int). */
RETRO_PIXEL_FORMAT_UNKNOWN = INT_MAX
} ;
enum retro_savestate_context
{
/* Standard savestate written to disk. */
RETRO_SAVESTATE_CONTEXT_NORMAL = 0 ,
/* Savestate where you are guaranteed that the same instance will load the save state.
* You can store internal pointers to code or data .
* It ' s still a full serialization and deserialization , and could be loaded or saved at any time .
* It won ' t be written to disk or sent over the network .
*/
RETRO_SAVESTATE_CONTEXT_RUNAHEAD_SAME_INSTANCE = 1 ,
/* Savestate where you are guaranteed that the same emulator binary will load that savestate.
* You can skip anything that would slow down saving or loading state but you can not store internal pointers .
* It won ' t be written to disk or sent over the network .
* Example : " Second Instance " runahead
*/
RETRO_SAVESTATE_CONTEXT_RUNAHEAD_SAME_BINARY = 2 ,
/* Savestate used within a rollback netplay feature.
* You should skip anything that would unnecessarily increase bandwidth usage .
* It won ' t be written to disk but it will be sent over the network .
*/
RETRO_SAVESTATE_CONTEXT_ROLLBACK_NETPLAY = 3 ,
/* Ensure sizeof() == sizeof(int). */
RETRO_SAVESTATE_CONTEXT_UNKNOWN = INT_MAX
} ;
struct retro_message
{
const char * msg ; /* Message to be displayed. */
unsigned frames ; /* Duration in frames of message. */
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
enum retro_message_target
{
RETRO_MESSAGE_TARGET_ALL = 0 ,
RETRO_MESSAGE_TARGET_OSD ,
RETRO_MESSAGE_TARGET_LOG
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
enum retro_message_type
{
RETRO_MESSAGE_TYPE_NOTIFICATION = 0 ,
RETRO_MESSAGE_TYPE_NOTIFICATION_ALT ,
RETRO_MESSAGE_TYPE_STATUS ,
RETRO_MESSAGE_TYPE_PROGRESS
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_message_ext
{
/* Message string to be displayed/logged */
const char * msg ;
/* Duration (in ms) of message when targeting the OSD */
unsigned duration ;
/* Message priority when targeting the OSD
* > When multiple concurrent messages are sent to
* the frontend and the frontend does not have the
* capacity to display them all , messages with the
* * highest * priority value should be shown
* > There is no upper limit to a message priority
* value ( within the bounds of the unsigned data type )
* > In the reference frontend ( RetroArch ) , the same
* priority values are used for frontend - generated
* notifications , which are typically assigned values
* between 0 and 3 depending upon importance */
unsigned priority ;
/* Message logging level (info, warn, error, etc.) */
enum retro_log_level level ;
/* Message destination: OSD, logging interface or both */
enum retro_message_target target ;
/* Message 'type' when targeting the OSD
* > RETRO_MESSAGE_TYPE_NOTIFICATION : Specifies that a
* message should be handled in identical fashion to
* a standard frontend - generated notification
* > RETRO_MESSAGE_TYPE_NOTIFICATION_ALT : Specifies that
* message is a notification that requires user attention
* or action , but that it should be displayed in a manner
* that differs from standard frontend - generated notifications .
* This would typically correspond to messages that should be
* displayed immediately ( independently from any internal
* frontend message queue ) , and / or which should be visually
* distinguishable from frontend - generated notifications .
* For example , a core may wish to inform the user of
* information related to a disk - change event . It is
* expected that the frontend itself may provide a
* notification in this case ; if the core sends a
* message of type RETRO_MESSAGE_TYPE_NOTIFICATION , an
* uncomfortable ' double - notification ' may occur . A message
* of RETRO_MESSAGE_TYPE_NOTIFICATION_ALT should therefore
* be presented such that visual conflict with regular
* notifications does not occur
* > RETRO_MESSAGE_TYPE_STATUS : Indicates that message
* is not a standard notification . This typically
* corresponds to ' status ' indicators , such as a core ' s
* internal FPS , which are intended to be displayed
* either permanently while a core is running , or in
* a manner that does not suggest user attention or action
* is required . ' Status ' type messages should therefore be
* displayed in a different on - screen location and in a manner
* easily distinguishable from both standard frontend - generated
* notifications and messages of type RETRO_MESSAGE_TYPE_NOTIFICATION_ALT
* > RETRO_MESSAGE_TYPE_PROGRESS : Indicates that message reports
* the progress of an internal core task . For example , in cases
* where a core itself handles the loading of content from a file ,
* this may correspond to the percentage of the file that has been
* read . Alternatively , an audio / video playback core may use a
* message of type RETRO_MESSAGE_TYPE_PROGRESS to display the current
* playback position as a percentage of the runtime . ' Progress ' type
* messages should therefore be displayed as a literal progress bar ,
* where :
* - ' retro_message_ext . msg ' is the progress bar title / label
* - ' retro_message_ext . progress ' determines the length of
* the progress bar
* NOTE : Message type is a * hint * , and may be ignored
* by the frontend . If a frontend lacks support for
* displaying messages via alternate means than standard
* frontend - generated notifications , it will treat * all *
* messages as having the type RETRO_MESSAGE_TYPE_NOTIFICATION */
enum retro_message_type type ;
/* Task progress when targeting the OSD and message is
* of type RETRO_MESSAGE_TYPE_PROGRESS
* > - 1 : Unmetered / indeterminate
* > 0 - 100 : Current progress percentage
* NOTE : Since message type is a hint , a frontend may ignore
* progress values . Where relevant , a core should therefore
* include progress percentage within the message string ,
* such that the message intent remains clear when displayed
* as a standard frontend - generated notification */
int8_t progress ;
} ;
/* Describes how the libretro implementation maps a libretro input bind
2019-12-31 21:02:35 +01:00
* to its internal input system through a human readable string .
* This string can be used to better let a user configure input . */
2024-03-04 11:41:01 -05:00
struct retro_input_descriptor
{
/* Associates given parameters with a description. */
unsigned port ;
unsigned device ;
unsigned index ;
unsigned id ;
/* Human readable description for parameters.
2019-12-31 21:02:35 +01:00
* The pointer must remain valid until
* retro_unload_game ( ) is called . */
2024-03-04 11:41:01 -05:00
const char * description ;
} ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
struct retro_system_info
{
/* All pointers are owned by libretro implementation, and pointers must
* remain valid until it is unloaded . */
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
const char * library_name ; /* Descriptive name of library. Should not
2019-12-31 21:02:35 +01:00
* contain any version numbers , etc . */
2024-03-04 11:41:01 -05:00
const char * library_version ; /* Descriptive version of core. */
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
const char * valid_extensions ; /* A string listing probably content
2019-12-31 21:02:35 +01:00
* extensions the core will be able to
* load , separated with pipe .
* I . e . " bin|rom|iso " .
* Typically used for a GUI to filter
* out extensions . */
2024-03-04 11:41:01 -05:00
/* Libretro cores that need to have direct access to their content
2019-12-31 21:02:35 +01:00
* 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
*/
2024-03-04 11:41:01 -05:00
bool need_fullpath ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* If true, the frontend is not allowed to extract any archives before
2019-12-31 21:02:35 +01:00
* loading the real content .
* Necessary for certain libretro implementations that load games
* from zipped archives . */
2024-03-04 11:41:01 -05:00
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 ;
} ;
struct retro_game_geometry
{
unsigned base_width ; /* Nominal video width of game. */
unsigned base_height ; /* Nominal video height of game. */
unsigned max_width ; /* Maximum possible width of game. */
unsigned max_height ; /* Maximum possible height of game. */
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
float aspect_ratio ; /* Nominal aspect ratio of game. If
2019-12-31 21:02:35 +01:00
* aspect_ratio is < = 0.0 , an aspect ratio
* of base_width / base_height is assumed .
* A frontend could override this setting ,
* if desired . */
2024-03-04 11:41:01 -05:00
} ;
struct retro_system_timing
{
double fps ; /* FPS of video content. */
double sample_rate ; /* Sampling rate of audio. */
} ;
struct retro_system_av_info
{
struct retro_game_geometry geometry ;
struct retro_system_timing timing ;
} ;
struct retro_variable
{
/* Variable to query in RETRO_ENVIRONMENT_GET_VARIABLE.
2019-12-31 21:02:35 +01:00
* If NULL , obtains the complete environment string if more
* complex parsing is necessary .
* The environment string is formatted as key - value pairs
* delimited by semicolons as so :
* " key1=value1;key2=value2;... "
*/
2024-03-04 11:41:01 -05:00
const char * key ;
/* Value to be obtained. If key does not exist, it is set to NULL. */
const char * value ;
} ;
struct retro_core_option_display
{
/* Variable to configure in RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY */
const char * key ;
/* Specifies whether variable should be displayed
* when presenting core options to the user */
bool visible ;
} ;
/* Maximum number of values permitted for a core option
* > Note : We have to set a maximum value due the limitations
* of the C language - i . e . it is not possible to create an
* array of structs each containing a variable sized array ,
* so the retro_core_option_definition values array must
* have a fixed size . The size limit of 128 is a balancing
* act - it needs to be large enough to support all ' sane '
* core options , but setting it too large may impact low memory
* platforms . In practise , if a core option has more than
* 128 values then the implementation is likely flawed .
* To quote the above API reference :
* " The number of possible options should be very limited
* i . e . it should be feasible to cycle through options
* without a keyboard . "
*/
# define RETRO_NUM_CORE_OPTION_VALUES_MAX 128
struct retro_core_option_value
{
/* Expected option value */
const char * value ;
/* Human-readable value label. If NULL, value itself
* will be displayed by the frontend */
const char * label ;
} ;
struct retro_core_option_definition
{
/* Variable to query in RETRO_ENVIRONMENT_GET_VARIABLE. */
const char * key ;
/* Human-readable core option description (used as menu label) */
const char * desc ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Human-readable core option information (used as menu sublabel) */
const char * info ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Array of retro_core_option_value structs, terminated by NULL */
struct retro_core_option_value values [ RETRO_NUM_CORE_OPTION_VALUES_MAX ] ;
/* Default core option value. Must match one of the values
* in the retro_core_option_value array , otherwise will be
* ignored */
const char * default_value ;
} ;
# ifdef __PS3__
# undef local
# endif
struct retro_core_options_intl
{
/* Pointer to an array of retro_core_option_definition structs
* - US English implementation
* - Must point to a valid array */
struct retro_core_option_definition * us ;
/* Pointer to an array of retro_core_option_definition structs
* - Implementation for current frontend language
* - May be NULL */
struct retro_core_option_definition * local ;
} ;
struct retro_core_option_v2_category
{
/* Variable uniquely identifying the
* option category . Valid key characters
* are [ a - z , A - Z , 0 - 9 , _ , - ] */
const char * key ;
/* Human-readable category description
* > Used as category menu label when
* frontend has core option category
* support */
const char * desc ;
/* Human-readable category information
* > Used as category menu sublabel when
* frontend has core option category
* support
* > Optional ( may be NULL or an empty
* string ) */
const char * info ;
} ;
struct retro_core_option_v2_definition
{
/* Variable to query in RETRO_ENVIRONMENT_GET_VARIABLE.
* Valid key characters are [ a - z , A - Z , 0 - 9 , _ , - ] */
const char * key ;
/* Human-readable core option description
* > Used as menu label when frontend does
* not have core option category support
* e . g . " Video > Aspect Ratio " */
const char * desc ;
/* Human-readable core option description
* > Used as menu label when frontend has
* core option category support
* e . g . " Aspect Ratio " , where associated
* retro_core_option_v2_category : : desc
* is " Video "
* > If empty or NULL , the string specified by
* desc will be used as the menu label
* > Will be ignored ( and may be set to NULL )
* if category_key is empty or NULL */
const char * desc_categorized ;
/* Human-readable core option information
* > Used as menu sublabel */
const char * info ;
/* Human-readable core option information
* > Used as menu sublabel when frontend
* has core option category support
* ( e . g . may be required when info text
* references an option by name / desc ,
* and the desc / desc_categorized text
* for that option differ )
* > If empty or NULL , the string specified by
* info will be used as the menu sublabel
* > Will be ignored ( and may be set to NULL )
* if category_key is empty or NULL */
const char * info_categorized ;
/* Variable specifying category (e.g. "video",
* " audio " ) that will be assigned to the option
* if frontend has core option category support .
* > Categorized options will be displayed in a
* subsection / submenu of the frontend core
* option interface
* > Specified string must match one of the
* retro_core_option_v2_category : : key values
* in the associated retro_core_option_v2_category
* array ; If no match is not found , specified
* string will be considered as NULL
* > If specified string is empty or NULL , option will
* have no category and will be shown at the top
* level of the frontend core option interface */
const char * category_key ;
/* Array of retro_core_option_value structs, terminated by NULL */
struct retro_core_option_value values [ RETRO_NUM_CORE_OPTION_VALUES_MAX ] ;
/* Default core option value. Must match one of the values
* in the retro_core_option_value array , otherwise will be
* ignored */
const char * default_value ;
} ;
struct retro_core_options_v2
{
/* Array of retro_core_option_v2_category structs,
* terminated by NULL
* > If NULL , all entries in definitions array
* will have no category and will be shown at
* the top level of the frontend core option
* interface
* > Will be ignored if frontend does not have
* core option category support */
struct retro_core_option_v2_category * categories ;
/* Array of retro_core_option_v2_definition structs,
* terminated by NULL */
struct retro_core_option_v2_definition * definitions ;
} ;
struct retro_core_options_v2_intl
{
/* Pointer to a retro_core_options_v2 struct
* > US English implementation
* > Must point to a valid struct */
struct retro_core_options_v2 * us ;
/* Pointer to a retro_core_options_v2 struct
* - Implementation for current frontend language
* - May be NULL */
struct retro_core_options_v2 * local ;
} ;
/* Used by the frontend to monitor changes in core option
* visibility . May be called each time any core option
* value is set via the frontend .
* - On each invocation , the core must update the visibility
* of any dynamically hidden options using the
* RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY environment
* callback .
* - On the first invocation , returns ' true ' if the visibility
* of any core option has changed since the last call of
* retro_load_game ( ) or retro_load_game_special ( ) .
* - On each subsequent invocation , returns ' true ' if the
* visibility of any core option has changed since the last
* time the function was called . */
typedef bool ( RETRO_CALLCONV * retro_core_options_update_display_callback_t ) ( void ) ;
struct retro_core_options_update_display_callback
{
retro_core_options_update_display_callback_t callback ;
} ;
struct retro_game_info
{
const char * path ; /* Path to game, UTF-8 encoded.
2019-12-31 21:02:35 +01:00
* 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 . */
2024-03-04 11:41:01 -05:00
const void * data ; /* Memory buffer of loaded game. Will be NULL
2019-12-31 21:02:35 +01:00
* if need_fullpath was set . */
2024-03-04 11:41:01 -05:00
size_t size ; /* Size of memory buffer. */
const char * meta ; /* String of implementation specific meta-data. */
} ;
2019-12-31 21:02:35 +01:00
# define RETRO_MEMORY_ACCESS_WRITE (1 << 0)
2024-03-04 11:41:01 -05:00
/* The core will write to the buffer provided by retro_framebuffer::data. */
2019-12-31 21:02:35 +01:00
# define RETRO_MEMORY_ACCESS_READ (1 << 1)
2024-03-04 11:41:01 -05:00
/* The core will read from retro_framebuffer::data. */
2019-12-31 21:02:35 +01:00
# define RETRO_MEMORY_TYPE_CACHED (1 << 0)
2024-03-04 11:41:01 -05:00
/* The memory in data is cached.
2019-12-31 21:02:35 +01:00
* If not cached , random writes and / or reading from the buffer is expected to be very slow . */
2024-03-04 11:41:01 -05:00
struct retro_framebuffer
{
void * data ; /* The framebuffer which the core can render into.
2019-12-31 21:02:35 +01:00
Set by frontend in GET_CURRENT_SOFTWARE_FRAMEBUFFER .
The initial contents of data are unspecified . */
2024-03-04 11:41:01 -05:00
unsigned width ; /* The framebuffer width used by the core. Set by core. */
unsigned height ; /* The framebuffer height used by the core. Set by core. */
size_t pitch ; /* The number of bytes between the beginning of a scanline,
2019-12-31 21:02:35 +01:00
and beginning of the next scanline .
Set by frontend in GET_CURRENT_SOFTWARE_FRAMEBUFFER . */
2024-03-04 11:41:01 -05:00
enum retro_pixel_format format ; /* The pixel format the core must use to render into data.
2019-12-31 21:02:35 +01:00
This format could differ from the format used in
SET_PIXEL_FORMAT .
Set by frontend in GET_CURRENT_SOFTWARE_FRAMEBUFFER . */
2024-03-04 11:41:01 -05:00
unsigned access_flags ; /* How the core will access the memory in the framebuffer.
2019-12-31 21:02:35 +01:00
RETRO_MEMORY_ACCESS_ * flags .
Set by core . */
2024-03-04 11:41:01 -05:00
unsigned memory_flags ; /* Flags telling core how the memory has been mapped.
2019-12-31 21:02:35 +01:00
RETRO_MEMORY_TYPE_ * flags .
Set by frontend in GET_CURRENT_SOFTWARE_FRAMEBUFFER . */
2024-03-04 11:41:01 -05:00
} ;
/* Used by a libretro core to override the current
* fastforwarding mode of the frontend */
struct retro_fastforwarding_override
{
/* Specifies the runtime speed multiplier that
* will be applied when ' fastforward ' is true .
* For example , a value of 5.0 when running 60 FPS
* content will cap the fast - forward rate at 300 FPS .
* Note that the target multiplier may not be achieved
* if the host hardware has insufficient processing
* power .
* Setting a value of 0.0 ( or greater than 0.0 but
* less than 1.0 ) will result in an uncapped
* fast - forward rate ( limited only by hardware
* capacity ) .
* If the value is negative , it will be ignored
* ( i . e . the frontend will use a runtime speed
* multiplier of its own choosing ) */
float ratio ;
/* If true, fastforwarding mode will be enabled.
* If false , fastforwarding mode will be disabled . */
bool fastforward ;
/* If true, and if supported by the frontend, an
* on - screen notification will be displayed while
* ' fastforward ' is true .
* If false , and if supported by the frontend , any
* on - screen fast - forward notifications will be
* suppressed */
bool notification ;
/* If true, the core will have sole control over
* when fastforwarding mode is enabled / disabled ;
* the frontend will not be able to change the
* state set by ' fastforward ' until either
* ' inhibit_toggle ' is set to false , or the core
* is unloaded */
bool inhibit_toggle ;
} ;
/* During normal operation. Rate will be equal to the core's internal FPS. */
# define RETRO_THROTTLE_NONE 0
/* While paused or stepping single frames. Rate will be 0. */
# define RETRO_THROTTLE_FRAME_STEPPING 1
/* During fast forwarding.
* Rate will be 0 if not specifically limited to a maximum speed . */
# define RETRO_THROTTLE_FAST_FORWARD 2
/* During slow motion. Rate will be less than the core's internal FPS. */
# define RETRO_THROTTLE_SLOW_MOTION 3
/* While rewinding recorded save states. 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 . Rate is the target refresh rate . */
# define RETRO_THROTTLE_VSYNC 5
/* When the frontend does not throttle in any way. Rate will be 0.
* An example could be if no vsync or audio output is active . */
# define RETRO_THROTTLE_UNBLOCKED 6
struct retro_throttle_state
{
/* The current throttling mode. Should be one of the values above. */
unsigned mode ;
/* How many times per second the frontend aims to call retro_run.
* 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 ;
} ;
/**
* 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 ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/**
* 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
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/**
* 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 args [ in ] 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 microphone [ in ] Opaque handle to the microphone
* whose parameters will be retrieved .
* @ param params [ out ] 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.1 kHz 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 ;
} ;
/**
* 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 ;
} ;
/* Callbacks */
/* Environment callback. Gives implementations a way of performing
2019-12-31 21:02:35 +01:00
* uncommon tasks . Extensible . */
2024-03-04 11:41:01 -05:00
typedef bool ( RETRO_CALLCONV * retro_environment_t ) ( unsigned cmd , void * data ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Render a frame. Pixel format is 15-bit 0RGB1555 native endian
2019-12-31 21:02:35 +01:00
* unless changed ( see RETRO_ENVIRONMENT_SET_PIXEL_FORMAT ) .
*
* Width and height specify dimensions of buffer .
* Pitch specifices length in bytes between two lines in buffer .
*
* 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 .
*/
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_video_refresh_t ) ( const void * data , unsigned width ,
unsigned height , size_t pitch ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Renders a single audio frame. Should only be used if implementation
2019-12-31 21:02:35 +01:00
* generates a single sample at a time .
* Format is signed 16 - bit native endian .
*/
2024-03-04 11:41:01 -05:00
typedef void ( RETRO_CALLCONV * retro_audio_sample_t ) ( int16_t left , int16_t right ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Renders multiple audio frames in one go.
2019-12-31 21:02:35 +01:00
*
* One frame is defined as a sample of left and right channels , interleaved .
* I . e . int16_t buf [ 4 ] = { l , r , l , r } ; would be 2 frames .
* Only one of the audio callbacks must ever be used .
*/
2024-03-04 11:41:01 -05:00
typedef size_t ( RETRO_CALLCONV * retro_audio_sample_batch_t ) ( const int16_t * data ,
size_t frames ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Polls input. */
typedef void ( RETRO_CALLCONV * retro_input_poll_t ) ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Queries for input for player 'port'. device will be masked with
2019-12-31 21:02:35 +01:00
* RETRO_DEVICE_MASK .
*
* Specialization of devices such as RETRO_DEVICE_JOYPAD_MULTITAP that
* have been set with retro_set_controller_port_device ( )
* will still use the higher level RETRO_DEVICE_JOYPAD to request input .
*/
2024-03-04 11:41:01 -05:00
typedef int16_t ( RETRO_CALLCONV * retro_input_state_t ) ( unsigned port , unsigned device ,
unsigned index , unsigned id ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Sets callbacks. retro_set_environment() is guaranteed to be called
2019-12-31 21:02:35 +01:00
* before retro_init ( ) .
*
* The rest of the set_ * functions are guaranteed to have been called
* before the first call to retro_run ( ) is made . */
2024-03-04 11:41:01 -05:00
RETRO_API void retro_set_environment ( retro_environment_t ) ;
RETRO_API void retro_set_video_refresh ( retro_video_refresh_t ) ;
RETRO_API void retro_set_audio_sample ( retro_audio_sample_t ) ;
RETRO_API void retro_set_audio_sample_batch ( retro_audio_sample_batch_t ) ;
RETRO_API void retro_set_input_poll ( retro_input_poll_t ) ;
RETRO_API void retro_set_input_state ( retro_input_state_t ) ;
/* Library global initialization/deinitialization. */
RETRO_API void retro_init ( void ) ;
RETRO_API void retro_deinit ( void ) ;
/* Must return RETRO_API_VERSION. Used to validate ABI compatibility
2019-12-31 21:02:35 +01:00
* when the API is revised . */
2024-03-04 11:41:01 -05:00
RETRO_API unsigned retro_api_version ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Gets statically known system info. Pointers provided in *info
2019-12-31 21:02:35 +01:00
* must be statically allocated .
* Can be called at any time , even before retro_init ( ) . */
2024-03-04 11:41:01 -05:00
RETRO_API void retro_get_system_info ( struct retro_system_info * info ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Gets information about system audio/video timings and geometry.
2019-12-31 21:02:35 +01:00
* Can be called only after retro_load_game ( ) has successfully completed .
* NOTE : The implementation of this function might not initialize every
* variable if needed .
* E . g . geom . aspect_ratio might not be initialized if core doesn ' t
* desire a particular aspect ratio . */
2024-03-04 11:41:01 -05:00
RETRO_API void retro_get_system_av_info ( struct retro_system_av_info * info ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Sets device to be used for player 'port'.
2019-12-31 21:02:35 +01:00
* By default , RETRO_DEVICE_JOYPAD is assumed to be plugged into all
* available ports .
* 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 .
*
* As part of the core ' s implementation of retro_set_controller_port_device ,
* the core should call 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 .
*/
2024-03-04 11:41:01 -05:00
RETRO_API void retro_set_controller_port_device ( unsigned port , unsigned device ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Resets the current game. */
RETRO_API void retro_reset ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Runs the game for one video frame.
2019-12-31 21:02:35 +01:00
* During retro_run ( ) , input_poll callback must be called at least once .
*
* If a frame is not rendered for reasons where a game " dropped " a frame ,
* this still counts as a frame , and retro_run ( ) should explicitly dupe
* a frame if GET_CAN_DUPE returns true .
* In this case , the video callback can take a NULL argument for data .
*/
2024-03-04 11:41:01 -05:00
RETRO_API void retro_run ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Returns the amount of data the implementation requires to serialize
2019-12-31 21:02:35 +01:00
* internal state ( save states ) .
* Between calls to retro_load_game ( ) and 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 .
*/
2024-03-04 11:41:01 -05:00
RETRO_API size_t retro_serialize_size ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Serializes internal state. If failed, or size is lower than
2019-12-31 21:02:35 +01:00
* retro_serialize_size ( ) , it should return false , true otherwise . */
2024-03-04 11:41:01 -05:00
RETRO_API bool retro_serialize ( void * data , size_t size ) ;
RETRO_API bool retro_unserialize ( const void * data , size_t size ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
RETRO_API void retro_cheat_reset ( void ) ;
RETRO_API void retro_cheat_set ( unsigned index , bool enabled , const char * code ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Loads a game.
2019-12-31 21:02:35 +01:00
* Return true to indicate successful loading and false to indicate load failure .
*/
2024-03-04 11:41:01 -05:00
RETRO_API bool retro_load_game ( const struct retro_game_info * game ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Loads a "special" kind of game. Should not be used,
2019-12-31 21:02:35 +01:00
* except in extreme cases . */
2024-03-04 11:41:01 -05:00
RETRO_API bool retro_load_game_special (
unsigned game_type ,
const struct retro_game_info * info , size_t num_info
) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Unloads the currently loaded game. Called before retro_deinit(void). */
RETRO_API void retro_unload_game ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Gets region of game. */
RETRO_API unsigned retro_get_region ( void ) ;
2019-12-31 21:02:35 +01:00
2024-03-04 11:41:01 -05:00
/* Gets region of memory. */
RETRO_API void * retro_get_memory_data ( unsigned id ) ;
RETRO_API size_t retro_get_memory_size ( unsigned id ) ;
2019-12-31 21:02:35 +01:00
# ifdef __cplusplus
}
# endif
2024-03-04 11:41:01 -05:00
# endif
