libretro.h 154 KB
Newer Older
jdgleaver's avatar
jdgleaver committed
1
/* Copyright (C) 2010-2020 The RetroArch team
LLeny's avatar
LLeny committed
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 *
 * ---------------------------------------------------------------------------------------
 * 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
extern "C" {
Alcaro's avatar
Alcaro committed
32
33
34
#endif

#ifndef __cplusplus
trioan's avatar
trioan committed
35
#if defined(_MSC_VER) && _MSC_VER < 1800 && !defined(SN_TARGET_PS3)
Alcaro's avatar
Alcaro committed
36
37
/* Hack applied for MSVC when compiling in C89 mode
 * as it isn't C99-compliant. */
LLeny's avatar
LLeny committed
38
39
40
41
42
43
44
45
#define bool unsigned char
#define true 1
#define false 0
#else
#include <stdbool.h>
#endif
#endif

46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
#ifndef RETRO_CALLCONV
#  if defined(__GNUC__) && defined(__i386__) && !defined(__x86_64__)
#    define RETRO_CALLCONV __attribute__((cdecl))
#  elif defined(_MSC_VER) && defined(_M_X86) && !defined(_M_X64)
#    define RETRO_CALLCONV __cdecl
#  else
#    define RETRO_CALLCONV /* all other platforms only have one calling convention each */
#  endif
#endif

#ifndef RETRO_API
#  if defined(_WIN32) || defined(__CYGWIN__) || defined(__MINGW32__)
#    ifdef RETRO_IMPORT_SYMBOLS
#      ifdef __GNUC__
#        define RETRO_API RETRO_CALLCONV __attribute__((__dllimport__))
#      else
#        define RETRO_API RETRO_CALLCONV __declspec(dllimport)
#      endif
#    else
#      ifdef __GNUC__
#        define RETRO_API RETRO_CALLCONV __attribute__((__dllexport__))
#      else
#        define RETRO_API RETRO_CALLCONV __declspec(dllexport)
#      endif
#    endif
#  else
#      if defined(__GNUC__) && __GNUC__ >= 4 && !defined(__CELLOS_LV2__)
#        define RETRO_API RETRO_CALLCONV __attribute__((__visibility__("default")))
#      else
#        define RETRO_API RETRO_CALLCONV
#      endif
#  endif
#endif

trioan's avatar
trioan committed
80
/* Used for checking API/ABI mismatches that can break libretro
Alcaro's avatar
Alcaro committed
81
82
83
 * implementations.
 * It is not incremented for compatible changes to the API.
 */
LLeny's avatar
LLeny committed
84
85
#define RETRO_API_VERSION         1

Alcaro's avatar
Alcaro committed
86
87
88
89
/*
 * Libretro's fundamental device abstractions.
 *
 * Libretro's input system consists of some standardized device types,
trioan's avatar
trioan committed
90
 * such as a joypad (with/without analog), mouse, keyboard, lightgun
Alcaro's avatar
Alcaro committed
91
92
 * and a pointer.
 *
trioan's avatar
trioan committed
93
 * The functionality of these devices are fixed, and individual cores
Alcaro's avatar
Alcaro committed
94
 * map their own concept of a controller to libretro's abstractions.
trioan's avatar
trioan committed
95
96
 * This makes it possible for frontends to map the abstract types to a
 * real input device, and not having to worry about binding input
Alcaro's avatar
Alcaro committed
97
98
99
100
101
102
103
104
 * correctly to arbitrary controller layouts.
 */

#define RETRO_DEVICE_TYPE_SHIFT         8
#define RETRO_DEVICE_MASK               ((1 << RETRO_DEVICE_TYPE_SHIFT) - 1)
#define RETRO_DEVICE_SUBCLASS(base, id) (((id + 1) << RETRO_DEVICE_TYPE_SHIFT) | base)

/* Input disabled. */
LLeny's avatar
LLeny committed
105
106
#define RETRO_DEVICE_NONE         0

trioan's avatar
trioan committed
107
108
/* The JOYPAD is called RetroPad. It is essentially a Super Nintendo
 * controller, but with additional L2/R2/L3/R3 buttons, similar to a
Alcaro's avatar
Alcaro committed
109
 * PS1 DualShock. */
LLeny's avatar
LLeny committed
110
111
#define RETRO_DEVICE_JOYPAD       1

Alcaro's avatar
Alcaro committed
112
113
/* The mouse is a simple mouse, similar to Super Nintendo's mouse.
 * X and Y coordinates are reported relatively to last poll (poll callback).
trioan's avatar
trioan committed
114
 * It is up to the libretro implementation to keep track of where the mouse
Alcaro's avatar
Alcaro committed
115
 * pointer is supposed to be on the screen.
trioan's avatar
trioan committed
116
 * The frontend must make sure not to interfere with its own hardware
Alcaro's avatar
Alcaro committed
117
118
 * mouse pointer.
 */
LLeny's avatar
LLeny committed
119
120
#define RETRO_DEVICE_MOUSE        2

Alcaro's avatar
Alcaro committed
121
/* KEYBOARD device lets one poll for raw key pressed.
trioan's avatar
trioan committed
122
 * It is poll based, so input callback will return with the current
Alcaro's avatar
Alcaro committed
123
124
125
126
 * pressed state.
 * For event/text based keyboard input, see
 * RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK.
 */
LLeny's avatar
LLeny committed
127
128
#define RETRO_DEVICE_KEYBOARD     3

trioan's avatar
trioan committed
129
130
131
132
133
134
135
136
137
/* 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.
 */
LLeny's avatar
LLeny committed
138
139
#define RETRO_DEVICE_LIGHTGUN     4

Alcaro's avatar
Alcaro committed
140
/* The ANALOG device is an extension to JOYPAD (RetroPad).
trioan's avatar
trioan committed
141
142
143
144
145
146
147
 * 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.
Alcaro's avatar
Alcaro committed
148
 */
LLeny's avatar
LLeny committed
149
150
#define RETRO_DEVICE_ANALOG       5

Alcaro's avatar
Alcaro committed
151
/* Abstracts the concept of a pointing mechanism, e.g. touch.
trioan's avatar
trioan committed
152
 * This allows libretro to query in absolute coordinates where on the
Alcaro's avatar
Alcaro committed
153
154
155
156
157
158
159
 * 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.
trioan's avatar
trioan committed
160
 * The "screen" is here defined as area that is passed to the frontend and
Alcaro's avatar
Alcaro committed
161
162
163
 * later displayed on the monitor.
 *
 * The frontend is free to scale/resize this screen as it sees fit, however,
trioan's avatar
trioan committed
164
 * (X, Y) = (-0x7fff, -0x7fff) will correspond to the top-left pixel of the
Alcaro's avatar
Alcaro committed
165
166
 * game image, etc.
 *
trioan's avatar
trioan committed
167
 * To check if the pointer coordinates are valid (e.g. a touch display
Alcaro's avatar
Alcaro committed
168
169
 * actually being touched), PRESSED returns 1 or 0.
 *
trioan's avatar
trioan committed
170
 * If using a mouse on a desktop, PRESSED will usually correspond to the
Alcaro's avatar
Alcaro committed
171
172
173
 * left mouse button, but this is a frontend decision.
 * PRESSED will only return 1 if the pointer is inside the game screen.
 *
trioan's avatar
trioan committed
174
 * For multi-touch, the index variable can be used to successively query
Alcaro's avatar
Alcaro committed
175
176
 * more presses.
 * If index = 0 returns true for _PRESSED, coordinates can be extracted
trioan's avatar
trioan committed
177
 * with _X, _Y for index = 0. One can then query _PRESSED, _X, _Y with
Alcaro's avatar
Alcaro committed
178
 * index = 1, and so on.
trioan's avatar
trioan committed
179
 * Eventually _PRESSED will return false for an index. No further presses
Alcaro's avatar
Alcaro committed
180
 * are registered at this point. */
LLeny's avatar
LLeny committed
181
182
#define RETRO_DEVICE_POINTER      6

Alcaro's avatar
Alcaro committed
183
/* Buttons for the RetroPad (JOYPAD).
trioan's avatar
trioan committed
184
 * The placement of these is equivalent to placements on the
Alcaro's avatar
Alcaro committed
185
 * Super Nintendo controller.
trioan's avatar
trioan committed
186
187
 * L2/R2/L3/R3 buttons correspond to the PS1 DualShock.
 * Also used as id values for RETRO_DEVICE_INDEX_ANALOG_BUTTON */
LLeny's avatar
LLeny committed
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
#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

trioan's avatar
trioan committed
205
206
#define RETRO_DEVICE_ID_JOYPAD_MASK    256

Alcaro's avatar
Alcaro committed
207
/* Index / Id values for ANALOG device. */
trioan's avatar
trioan committed
208
209
210
211
212
#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
LLeny's avatar
LLeny committed
213

Alcaro's avatar
Alcaro committed
214
/* Id values for MOUSE. */
215
216
217
218
219
220
221
222
223
#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
trioan's avatar
trioan committed
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
#define RETRO_DEVICE_ID_MOUSE_BUTTON_4         9
#define RETRO_DEVICE_ID_MOUSE_BUTTON_5         10

/* Id values for LIGHTGUN. */
#define RETRO_DEVICE_ID_LIGHTGUN_SCREEN_X        13 /*Absolute Position*/
#define RETRO_DEVICE_ID_LIGHTGUN_SCREEN_Y        14 /*Absolute*/
#define RETRO_DEVICE_ID_LIGHTGUN_IS_OFFSCREEN    15 /*Status Check*/
#define RETRO_DEVICE_ID_LIGHTGUN_TRIGGER          2
#define RETRO_DEVICE_ID_LIGHTGUN_RELOAD          16 /*Forced off-screen shot*/
#define RETRO_DEVICE_ID_LIGHTGUN_AUX_A            3
#define RETRO_DEVICE_ID_LIGHTGUN_AUX_B            4
#define RETRO_DEVICE_ID_LIGHTGUN_START            6
#define RETRO_DEVICE_ID_LIGHTGUN_SELECT           7
#define RETRO_DEVICE_ID_LIGHTGUN_AUX_C            8
#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_UP          9
#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_DOWN       10
#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_LEFT       11
#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_RIGHT      12
/* deprecated */
#define RETRO_DEVICE_ID_LIGHTGUN_X                0 /*Relative Position*/
#define RETRO_DEVICE_ID_LIGHTGUN_Y                1 /*Relative*/
#define RETRO_DEVICE_ID_LIGHTGUN_CURSOR           3 /*Use Aux:A*/
#define RETRO_DEVICE_ID_LIGHTGUN_TURBO            4 /*Use Aux:B*/
#define RETRO_DEVICE_ID_LIGHTGUN_PAUSE            5 /*Use Start*/
LLeny's avatar
LLeny committed
248

Alcaro's avatar
Alcaro committed
249
/* Id values for POINTER. */
LLeny's avatar
LLeny committed
250
251
252
#define RETRO_DEVICE_ID_POINTER_X         0
#define RETRO_DEVICE_ID_POINTER_Y         1
#define RETRO_DEVICE_ID_POINTER_PRESSED   2
trioan's avatar
trioan committed
253
#define RETRO_DEVICE_ID_POINTER_COUNT     3
LLeny's avatar
LLeny committed
254

Alcaro's avatar
Alcaro committed
255
/* Returned from retro_get_region(). */
LLeny's avatar
LLeny committed
256
257
258
#define RETRO_REGION_NTSC  0
#define RETRO_REGION_PAL   1

Alcaro's avatar
Alcaro committed
259
260
261
/* Id values for LANGUAGE */
enum retro_language
{
Libretro-Admin's avatar
Update    
Libretro-Admin committed
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
   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,
trioan's avatar
trioan committed
278
279
280
   RETRO_LANGUAGE_ARABIC              = 16,
   RETRO_LANGUAGE_GREEK               = 17,
   RETRO_LANGUAGE_TURKISH             = 18,
jdgleaver's avatar
jdgleaver committed
281
282
283
284
   RETRO_LANGUAGE_SLOVAK              = 19,
   RETRO_LANGUAGE_PERSIAN             = 20,
   RETRO_LANGUAGE_HEBREW              = 21,
   RETRO_LANGUAGE_ASTURIAN            = 22,
Alcaro's avatar
Alcaro committed
285
286
287
   RETRO_LANGUAGE_LAST,

   /* Ensure sizeof(enum) == sizeof(int) */
trioan's avatar
trioan committed
288
   RETRO_LANGUAGE_DUMMY          = INT_MAX
Alcaro's avatar
Alcaro committed
289
290
291
};

/* Passed to retro_get_memory_data/size().
trioan's avatar
trioan committed
292
 * If the memory type doesn't apply to the
Alcaro's avatar
Alcaro committed
293
294
 * implementation NULL/0 can be returned.
 */
LLeny's avatar
LLeny committed
295
296
#define RETRO_MEMORY_MASK        0xff

Alcaro's avatar
Alcaro committed
297
298
299
300
301
/* 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. */
LLeny's avatar
LLeny committed
302
303
#define RETRO_MEMORY_SAVE_RAM    0

Alcaro's avatar
Alcaro committed
304
305
306
/* 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.
 */
LLeny's avatar
LLeny committed
307
308
#define RETRO_MEMORY_RTC         1

Alcaro's avatar
Alcaro committed
309
/* System ram lets a frontend peek into a game systems main RAM. */
LLeny's avatar
LLeny committed
310
311
#define RETRO_MEMORY_SYSTEM_RAM  2

Alcaro's avatar
Alcaro committed
312
/* Video ram lets a frontend peek into a game systems video RAM (VRAM). */
LLeny's avatar
LLeny committed
313
314
#define RETRO_MEMORY_VIDEO_RAM   3

Alcaro's avatar
Alcaro committed
315
/* Keysyms used for ID in input state callback when polling RETRO_KEYBOARD. */
LLeny's avatar
LLeny committed
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
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,
trioan's avatar
trioan committed
390
391
392
393
   RETROK_LEFTBRACE      = 123,
   RETROK_BAR            = 124,
   RETROK_RIGHTBRACE     = 125,
   RETROK_TILDE          = 126,
LLeny's avatar
LLeny committed
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
   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,
trioan's avatar
trioan committed
464
   RETROK_OEM_102        = 323,
LLeny's avatar
LLeny committed
465
466
467

   RETROK_LAST,

Alcaro's avatar
Alcaro committed
468
   RETROK_DUMMY          = INT_MAX /* Ensure sizeof(enum) == sizeof(int) */
LLeny's avatar
LLeny committed
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
};

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,

Alcaro's avatar
Alcaro committed
484
   RETROKMOD_DUMMY = INT_MAX /* Ensure sizeof(enum) == sizeof(int) */
LLeny's avatar
LLeny committed
485
486
};

trioan's avatar
trioan committed
487
/* If set, this call is not part of the public libretro API yet. It can
Alcaro's avatar
Alcaro committed
488
 * change or be removed at any time. */
LLeny's avatar
LLeny committed
489
#define RETRO_ENVIRONMENT_EXPERIMENTAL 0x10000
Alcaro's avatar
Alcaro committed
490
/* Environment callback to be used internally in frontend. */
491
#define RETRO_ENVIRONMENT_PRIVATE 0x20000
LLeny's avatar
LLeny committed
492

Alcaro's avatar
Alcaro committed
493
494
495
/* Environment commands. */
#define RETRO_ENVIRONMENT_SET_ROTATION  1  /* const unsigned * --
                                            * Sets screen rotation of graphics.
trioan's avatar
trioan committed
496
                                            * Valid values are 0, 1, 2, 3, which rotates screen by 0, 90, 180,
Alcaro's avatar
Alcaro committed
497
498
499
                                            * 270 degrees counter-clockwise respectively.
                                            */
#define RETRO_ENVIRONMENT_GET_OVERSCAN  2  /* bool * --
trioan's avatar
trioan committed
500
501
502
503
                                            * 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,
Alcaro's avatar
Alcaro committed
504
505
506
507
508
509
510
                                            * 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.
                                            */

trioan's avatar
trioan committed
511
                                           /* Environ 4, 5 are no longer supported (GET_VARIABLE / SET_VARIABLES),
Alcaro's avatar
Alcaro committed
512
513
514
515
                                            * and reserved to avoid possible ABI clash.
                                            */

#define RETRO_ENVIRONMENT_SET_MESSAGE   6  /* const struct retro_message * --
trioan's avatar
trioan committed
516
                                            * Sets a message to be displayed in implementation-specific manner
Alcaro's avatar
Alcaro committed
517
                                            * for a certain amount of 'frames'.
trioan's avatar
trioan committed
518
519
                                            * Should not be used for trivial messages, which should simply be
                                            * logged via RETRO_ENVIRONMENT_GET_LOG_INTERFACE (or as a
Alcaro's avatar
Alcaro committed
520
521
522
523
524
525
526
                                            * 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.
                                            */
LLeny's avatar
LLeny committed
527
#define RETRO_ENVIRONMENT_SET_PERFORMANCE_LEVEL 8
Alcaro's avatar
Alcaro committed
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
                                           /* const unsigned * --
                                            * 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().
                                            */
LLeny's avatar
LLeny committed
544
#define RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY 9
Alcaro's avatar
Alcaro committed
545
546
                                           /* const char ** --
                                            * Returns the "system" directory of the frontend.
trioan's avatar
trioan committed
547
                                            * This directory can be used to store system specific
Alcaro's avatar
Alcaro committed
548
549
550
551
552
                                            * 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.
                                            *
trioan's avatar
trioan committed
553
                                            * NOTE: Some cores used this folder also for "save" data such as
Alcaro's avatar
Alcaro committed
554
                                            * memory cards, etc, for lack of a better place to put it.
trioan's avatar
trioan committed
555
                                            * This is now discouraged, and if possible, cores should try to
Alcaro's avatar
Alcaro committed
556
557
                                            * use the new GET_SAVE_DIRECTORY.
                                            */
LLeny's avatar
LLeny committed
558
#define RETRO_ENVIRONMENT_SET_PIXEL_FORMAT 10
Alcaro's avatar
Alcaro committed
559
560
561
562
                                           /* const enum retro_pixel_format * --
                                            * 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).
trioan's avatar
trioan committed
563
                                            * If the call returns false, the frontend does not support this pixel
Alcaro's avatar
Alcaro committed
564
565
                                            * format.
                                            *
trioan's avatar
trioan committed
566
                                            * This function should be called inside retro_load_game() or
Alcaro's avatar
Alcaro committed
567
568
                                            * retro_get_system_av_info().
                                            */
LLeny's avatar
LLeny committed
569
#define RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS 11
Alcaro's avatar
Alcaro committed
570
571
572
                                           /* const struct retro_input_descriptor * --
                                            * Sets an array of retro_input_descriptors.
                                            * It is up to the frontend to present this in a usable way.
trioan's avatar
trioan committed
573
                                            * The array is terminated by retro_input_descriptor::description
Alcaro's avatar
Alcaro committed
574
                                            * being set to NULL.
trioan's avatar
trioan committed
575
                                            * This function can be called at any time, but it is recommended
Alcaro's avatar
Alcaro committed
576
577
                                            * to call it as early as possible.
                                            */
LLeny's avatar
LLeny committed
578
#define RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK 12
Alcaro's avatar
Alcaro committed
579
580
581
                                           /* const struct retro_keyboard_callback * --
                                            * Sets a callback function used to notify core about keyboard events.
                                            */
LLeny's avatar
LLeny committed
582
#define RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE 13
Alcaro's avatar
Alcaro committed
583
                                           /* const struct retro_disk_control_callback * --
trioan's avatar
trioan committed
584
                                            * Sets an interface which frontend can use to eject and insert
Alcaro's avatar
Alcaro committed
585
                                            * disk images.
trioan's avatar
trioan committed
586
                                            * This is used for games which consist of multiple images and
Alcaro's avatar
Alcaro committed
587
588
                                            * must be manually swapped out by the user (e.g. PSX).
                                            */
LLeny's avatar
LLeny committed
589
#define RETRO_ENVIRONMENT_SET_HW_RENDER 14
Alcaro's avatar
Alcaro committed
590
                                           /* struct retro_hw_render_callback * --
trioan's avatar
trioan committed
591
                                            * Sets an interface to let a libretro core render with
Alcaro's avatar
Alcaro committed
592
593
                                            * hardware acceleration.
                                            * Should be called in retro_load_game().
trioan's avatar
trioan committed
594
                                            * If successful, libretro cores will be able to render to a
Alcaro's avatar
Alcaro committed
595
                                            * frontend-provided framebuffer.
trioan's avatar
trioan committed
596
                                            * The size of this framebuffer will be at least as large as
Alcaro's avatar
Alcaro committed
597
                                            * max_width/max_height provided in get_av_info().
trioan's avatar
trioan committed
598
                                            * If HW rendering is used, pass only RETRO_HW_FRAME_BUFFER_VALID or
Alcaro's avatar
Alcaro committed
599
600
                                            * NULL to retro_video_refresh_t.
                                            */
LLeny's avatar
LLeny committed
601
#define RETRO_ENVIRONMENT_GET_VARIABLE 15
Alcaro's avatar
Alcaro committed
602
603
604
                                           /* struct retro_variable * --
                                            * Interface to acquire user-defined information from environment
                                            * that cannot feasibly be supported in a multi-system way.
trioan's avatar
trioan committed
605
                                            * 'key' should be set to a key which has already been set by
Alcaro's avatar
Alcaro committed
606
607
608
                                            * SET_VARIABLES.
                                            * 'data' will be set to a value or NULL.
                                            */
LLeny's avatar
LLeny committed
609
#define RETRO_ENVIRONMENT_SET_VARIABLES 16
Alcaro's avatar
Alcaro committed
610
611
                                           /* const struct retro_variable * --
                                            * Allows an implementation to signal the environment
trioan's avatar
trioan committed
612
                                            * which variables it might want to check for later using
Alcaro's avatar
Alcaro committed
613
                                            * GET_VARIABLE.
trioan's avatar
trioan committed
614
                                            * This allows the frontend to present these variables to
Alcaro's avatar
Alcaro committed
615
                                            * a user dynamically.
trioan's avatar
trioan committed
616
617
618
619
620
                                            * 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.
Alcaro's avatar
Alcaro committed
621
                                            *
trioan's avatar
trioan committed
622
                                            * 'data' points to an array of retro_variable structs
Alcaro's avatar
Alcaro committed
623
                                            * terminated by a { NULL, NULL } element.
trioan's avatar
trioan committed
624
625
                                            * retro_variable::key should be namespaced to not collide
                                            * with other implementations' keys. E.g. A core called
Alcaro's avatar
Alcaro committed
626
                                            * 'foo' should use keys named as 'foo_option'.
trioan's avatar
trioan committed
627
628
                                            * retro_variable::value should contain a human readable
                                            * description of the key as well as a '|' delimited list
Alcaro's avatar
Alcaro committed
629
630
                                            * of expected values.
                                            *
trioan's avatar
trioan committed
631
632
                                            * The number of possible options should be very limited,
                                            * i.e. it should be feasible to cycle through options
Alcaro's avatar
Alcaro committed
633
634
635
636
637
638
639
                                            * without a keyboard.
                                            *
                                            * First entry should be treated as a default.
                                            *
                                            * Example entry:
                                            * { "foo_option", "Speed hack coprocessor X; false|true" }
                                            *
trioan's avatar
trioan committed
640
641
                                            * Text before first ';' is description. This ';' must be
                                            * followed by a space, and followed by a list of possible
Alcaro's avatar
Alcaro committed
642
643
                                            * values split up with '|'.
                                            *
trioan's avatar
trioan committed
644
                                            * Only strings are operated on. The possible values will
Alcaro's avatar
Alcaro committed
645
646
                                            * generally be displayed and stored as-is by the frontend.
                                            */
LLeny's avatar
LLeny committed
647
#define RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE 17
Alcaro's avatar
Alcaro committed
648
649
650
651
652
                                           /* bool * --
                                            * 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.
                                            */
LLeny's avatar
LLeny committed
653
#define RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME 18
Alcaro's avatar
Alcaro committed
654
                                           /* const bool * --
trioan's avatar
trioan committed
655
                                            * If true, the libretro implementation supports calls to
Alcaro's avatar
Alcaro committed
656
657
658
659
                                            * 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.
                                            */
LLeny's avatar
LLeny committed
660
#define RETRO_ENVIRONMENT_GET_LIBRETRO_PATH 19
Alcaro's avatar
Alcaro committed
661
                                           /* const char ** --
trioan's avatar
trioan committed
662
                                            * Retrieves the absolute path from where this libretro
Alcaro's avatar
Alcaro committed
663
                                            * implementation was loaded.
trioan's avatar
trioan committed
664
665
                                            * NULL is returned if the libretro was loaded statically
                                            * (i.e. linked statically to frontend), or if the path cannot be
Alcaro's avatar
Alcaro committed
666
                                            * determined.
trioan's avatar
trioan committed
667
                                            * Mostly useful in cooperation with SET_SUPPORT_NO_GAME as assets can
Alcaro's avatar
Alcaro committed
668
669
                                            * be loaded without ugly hacks.
                                            */
trioan's avatar
trioan committed
670
671

                                           /* Environment 20 was an obsolete version of SET_AUDIO_CALLBACK.
Alcaro's avatar
Alcaro committed
672
673
                                            * It was not used by any known core at the time,
                                            * and was removed from the API. */
trioan's avatar
trioan committed
674
675
676
677
678
679
680
681
682
#define RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK 21
                                           /* const struct retro_frame_time_callback * --
                                            * 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..
                                            */
683
#define RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK 22
Alcaro's avatar
Alcaro committed
684
                                           /* const struct retro_audio_callback * --
trioan's avatar
trioan committed
685
                                            * Sets an interface which is used to notify a libretro core about audio
Alcaro's avatar
Alcaro committed
686
                                            * being available for writing.
trioan's avatar
trioan committed
687
                                            * The callback can be called from any thread, so a core using this must
Alcaro's avatar
Alcaro committed
688
                                            * have a thread safe audio implementation.
trioan's avatar
trioan committed
689
                                            * It is intended for games where audio and video are completely
Alcaro's avatar
Alcaro committed
690
                                            * asynchronous and audio can be generated on the fly.
trioan's avatar
trioan committed
691
                                            * This interface is not recommended for use with emulators which have
Alcaro's avatar
Alcaro committed
692
693
                                            * highly synchronous audio.
                                            *
trioan's avatar
trioan committed
694
                                            * The callback only notifies about writability; the libretro core still
Alcaro's avatar
Alcaro committed
695
                                            * has to call the normal audio callbacks
trioan's avatar
trioan committed
696
                                            * to write audio. The audio callbacks must be called from within the
Alcaro's avatar
Alcaro committed
697
698
699
700
                                            * 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.
                                            *
trioan's avatar
trioan committed
701
702
703
                                            * 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
Alcaro's avatar
Alcaro committed
704
705
                                            * implement the "normal" audio interface.
                                            *
trioan's avatar
trioan committed
706
                                            * A libretro core using SET_AUDIO_CALLBACK should also make use of
Alcaro's avatar
Alcaro committed
707
708
                                            * SET_FRAME_TIME_CALLBACK.
                                            */
709
#define RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE 23
Alcaro's avatar
Alcaro committed
710
                                           /* struct retro_rumble_interface * --
trioan's avatar
trioan committed
711
                                            * Gets an interface which is used by a libretro core to set
Alcaro's avatar
Alcaro committed
712
                                            * state of rumble motors in controllers.
trioan's avatar
trioan committed
713
                                            * A strong and weak motor is supported, and they can be
Alcaro's avatar
Alcaro committed
714
715
                                            * controlled indepedently.
                                            */
716
#define RETRO_ENVIRONMENT_GET_INPUT_DEVICE_CAPABILITIES 24
Alcaro's avatar
Alcaro committed
717
                                           /* uint64_t * --
trioan's avatar
trioan committed
718
                                            * Gets a bitmask telling which device type are expected to be
Alcaro's avatar
Alcaro committed
719
                                            * handled properly in a call to retro_input_state_t.
trioan's avatar
trioan committed
720
                                            * Devices which are not handled or recognized always return
Alcaro's avatar
Alcaro committed
721
722
723
724
                                            * 0 in retro_input_state_t.
                                            * Example bitmask: caps = (1 << RETRO_DEVICE_JOYPAD) | (1 << RETRO_DEVICE_ANALOG).
                                            * Should only be called in retro_run().
                                            */
725
#define RETRO_ENVIRONMENT_GET_SENSOR_INTERFACE (25 | RETRO_ENVIRONMENT_EXPERIMENTAL)
Alcaro's avatar
Alcaro committed
726
727
728
                                           /* struct retro_sensor_interface * --
                                            * Gets access to the sensor interface.
                                            * The purpose of this interface is to allow
trioan's avatar
trioan committed
729
                                            * setting state related to sensors such as polling rate,
Alcaro's avatar
Alcaro committed
730
                                            * enabling/disable it entirely, etc.
trioan's avatar
trioan committed
731
                                            * Reading sensor state is done via the normal
Alcaro's avatar
Alcaro committed
732
733
                                            * input_state_callback API.
                                            */
734
#define RETRO_ENVIRONMENT_GET_CAMERA_INTERFACE (26 | RETRO_ENVIRONMENT_EXPERIMENTAL)
Alcaro's avatar
Alcaro committed
735
736
                                           /* struct retro_camera_callback * --
                                            * Gets an interface to a video camera driver.
trioan's avatar
trioan committed
737
                                            * A libretro core can use this interface to get access to a
Alcaro's avatar
Alcaro committed
738
                                            * video camera.
trioan's avatar
trioan committed
739
                                            * New video frames are delivered in a callback in same
Alcaro's avatar
Alcaro committed
740
741
742
743
                                            * thread as retro_run().
                                            *
                                            * GET_CAMERA_INTERFACE should be called in retro_load_game().
                                            *
trioan's avatar
trioan committed
744
                                            * Depending on the camera implementation used, camera frames
Alcaro's avatar
Alcaro committed
745
746
747
                                            * will be delivered as a raw framebuffer,
                                            * or as an OpenGL texture directly.
                                            *
trioan's avatar
trioan committed
748
                                            * The core has to tell the frontend here which types of
Alcaro's avatar
Alcaro committed
749
                                            * buffers can be handled properly.
trioan's avatar
trioan committed
750
                                            * An OpenGL texture can only be handled when using a
Alcaro's avatar
Alcaro committed
751
                                            * libretro GL core (SET_HW_RENDER).
trioan's avatar
trioan committed
752
                                            * It is recommended to use a libretro GL core when
Alcaro's avatar
Alcaro committed
753
754
                                            * using camera interface.
                                            *
trioan's avatar
trioan committed
755
                                            * The camera is not started automatically. The retrieved start/stop
Alcaro's avatar
Alcaro committed
756
757
758
                                            * functions must be used to explicitly
                                            * start and stop the camera driver.
                                            */
759
#define RETRO_ENVIRONMENT_GET_LOG_INTERFACE 27
Alcaro's avatar
Alcaro committed
760
                                           /* struct retro_log_callback * --
trioan's avatar
trioan committed
761
                                            * Gets an interface for logging. This is useful for
Alcaro's avatar
Alcaro committed
762
                                            * logging in a cross-platform way
trioan's avatar
trioan committed
763
                                            * as certain platforms cannot use stderr for logging.
Alcaro's avatar
Alcaro committed
764
765
                                            * It also allows the frontend to
                                            * show logging information in a more suitable way.
trioan's avatar
trioan committed
766
                                            * If this interface is not used, libretro cores should
Alcaro's avatar
Alcaro committed
767
768
                                            * log to stderr as desired.
                                            */
Libretro-Admin's avatar
Libretro-Admin committed
769
#define RETRO_ENVIRONMENT_GET_PERF_INTERFACE 28
Alcaro's avatar
Alcaro committed
770
                                           /* struct retro_perf_callback * --
trioan's avatar
trioan committed
771
772
                                            * Gets an interface for performance counters. This is useful
                                            * for performance logging in a cross-platform way and for detecting
Alcaro's avatar
Alcaro committed
773
774
775
776
777
                                            * architecture-specific features, such as SIMD support.
                                            */
#define RETRO_ENVIRONMENT_GET_LOCATION_INTERFACE 29
                                           /* struct retro_location_callback * --
                                            * Gets access to the location interface.
trioan's avatar
trioan committed
778
                                            * The purpose of this interface is to be able to retrieve
Alcaro's avatar
Alcaro committed
779
780
781
                                            * location-based information from the host device,
                                            * such as current latitude / longitude.
                                            */
782
783
#define RETRO_ENVIRONMENT_GET_CONTENT_DIRECTORY 30 /* Old name, kept for compatibility. */
#define RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY 30
Alcaro's avatar
Alcaro committed
784
                                           /* const char ** --
785
                                            * Returns the "core assets" directory of the frontend.
trioan's avatar
trioan committed
786
                                            * This directory can be used to store specific assets that the
Alcaro's avatar
Alcaro committed
787
788
789
790
791
792
793
794
                                            * 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
                                           /* const char ** --
trioan's avatar
trioan committed
795
796
797
                                            * 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
Alcaro's avatar
Alcaro committed
798
799
                                            * cannot use the regular memory interface (retro_get_memory_data()).
                                            *
trioan's avatar
trioan committed
800
801
802
803
804
805
806
                                            * 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.
Alcaro's avatar
Alcaro committed
807
808
809
                                            */
#define RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO 32
                                           /* const struct retro_system_av_info * --
trioan's avatar
trioan committed
810
                                            * Sets a new av_info structure. This can only be called from
Alcaro's avatar
Alcaro committed
811
                                            * within retro_run().
trioan's avatar
trioan committed
812
                                            * This should *only* be used if the core is completely altering the
Alcaro's avatar
Alcaro committed
813
                                            * internal resolutions, aspect ratios, timings, sampling rate, etc.
trioan's avatar
trioan committed
814
                                            * Calling this can require a full reinitialization of video/audio
Alcaro's avatar
Alcaro committed
815
816
                                            * drivers in the frontend,
                                            *
trioan's avatar
trioan committed
817
                                            * so it is important to call it very sparingly, and usually only with
Alcaro's avatar
Alcaro committed
818
                                            * the users explicit consent.
trioan's avatar
trioan committed
819
                                            * An eventual driver reinitialize will happen so that video and
Alcaro's avatar
Alcaro committed
820
                                            * audio callbacks
trioan's avatar
trioan committed
821
                                            * happening after this call within the same retro_run() call will
Alcaro's avatar
Alcaro committed
822
823
                                            * target the newly initialized driver.
                                            *
trioan's avatar
trioan committed
824
                                            * This callback makes it possible to support configurable resolutions
Alcaro's avatar
Alcaro committed
825
826
827
                                            * in games, which can be useful to
                                            * avoid setting the "worst case" in max_width/max_height.
                                            *
trioan's avatar
trioan committed
828
                                            * ***HIGHLY RECOMMENDED*** Do not call this callback every time
Alcaro's avatar
Alcaro committed
829
                                            * resolution changes in an emulator core if it's
trioan's avatar
trioan committed
830
                                            * expected to be a temporary change, for the reasons of possible
Alcaro's avatar
Alcaro committed
831
                                            * driver reinitialization.
trioan's avatar
trioan committed
832
833
834
835
                                            * 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
Alcaro's avatar
Alcaro committed
836
837
                                            * of SET_SYSTEM_AV_INFO.
                                            *
trioan's avatar
trioan committed
838
                                            * If this returns false, the frontend does not acknowledge a
Alcaro's avatar
Alcaro committed
839
840
841
842
                                            * changed av_info struct.
                                            */
#define RETRO_ENVIRONMENT_SET_PROC_ADDRESS_CALLBACK 33
                                           /* const struct retro_get_proc_address_interface * --
trioan's avatar
trioan committed
843
                                            * Allows a libretro core to announce support for the
Alcaro's avatar
Alcaro committed
844
                                            * get_proc_address() interface.
trioan's avatar
trioan committed
845
                                            * This interface allows for a standard way to extend libretro where
Alcaro's avatar
Alcaro committed
846
847
848
                                            * use of environment calls are too indirect,
                                            * e.g. for cases where the frontend wants to call directly into the core.
                                            *
trioan's avatar
trioan committed
849
                                            * If a core wants to expose this interface, SET_PROC_ADDRESS_CALLBACK
Alcaro's avatar
Alcaro committed
850
851
852
853
854
                                            * **MUST** be called from within retro_set_environment().
                                            */
#define RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO 34
                                           /* const struct retro_subsystem_info * --
                                            * This environment call introduces the concept of libretro "subsystems".
trioan's avatar
trioan committed
855
                                            * A subsystem is a variant of a libretro core which supports
Alcaro's avatar
Alcaro committed
856
                                            * different kinds of games.
trioan's avatar
trioan committed
857
                                            * The purpose of this is to support e.g. emulators which might
Alcaro's avatar
Alcaro committed
858
                                            * have special needs, e.g. Super Nintendo's Super GameBoy, Sufami Turbo.
trioan's avatar
trioan committed
859
                                            * It can also be used to pick among subsystems in an explicit way
Alcaro's avatar
Alcaro committed
860
861
862
                                            * if the libretro implementation is a multi-system emulator itself.
                                            *
                                            * Loading a game via a subsystem is done with retro_load_game_special(),
trioan's avatar
trioan committed
863
                                            * and this environment call allows a libretro core to expose which
Alcaro's avatar
Alcaro committed
864
                                            * subsystems are supported for use with retro_load_game_special().
trioan's avatar
trioan committed
865
                                            * A core passes an array of retro_game_special_info which is terminated
Alcaro's avatar
Alcaro committed
866
867
868
869
870
871
872
                                            * 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
                                           /* const struct retro_controller_info * --
trioan's avatar
trioan committed
873
874
                                            * This environment call lets a libretro core tell the frontend
                                            * which controller subclasses are recognized in calls to
Alcaro's avatar
Alcaro committed
875
876
                                            * retro_set_controller_port_device().
                                            *
trioan's avatar
trioan committed
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
                                            * 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,
Alcaro's avatar
Alcaro committed
907
908
909
910
                                            * libretro should only poll input based on the base input device types.
                                            */
#define RETRO_ENVIRONMENT_SET_MEMORY_MAPS (36 | RETRO_ENVIRONMENT_EXPERIMENTAL)
                                           /* const struct retro_memory_map * --
trioan's avatar
trioan committed
911
                                            * This environment call lets a libretro core tell the frontend
Alcaro's avatar
Alcaro committed
912
913
914
                                            * about the memory maps this core emulates.
                                            * This can be used to implement, for example, cheats in a core-agnostic way.
                                            *
trioan's avatar
trioan committed
915
                                            * Should only be used by emulators; it doesn't make much sense for
Alcaro's avatar
Alcaro committed
916
                                            * anything else.
trioan's avatar
trioan committed
917
                                            * It is recommended to expose all relevant pointers through
Alcaro's avatar
Alcaro committed
918
919
920
921
922
923
                                            * retro_get_memory_* as well.
                                            *
                                            * Can be called from retro_init and retro_load_game.
                                            */
#define RETRO_ENVIRONMENT_SET_GEOMETRY 37
                                           /* const struct retro_game_geometry * --
trioan's avatar
trioan committed
924
925
                                            * This environment call is similar to SET_SYSTEM_AV_INFO for changing
                                            * video parameters, but provides a guarantee that drivers will not be
Alcaro's avatar
Alcaro committed
926
927
928
                                            * reinitialized.
                                            * This can only be called from within retro_run().
                                            *
trioan's avatar
trioan committed
929
930
                                            * 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
Alcaro's avatar
Alcaro committed
931
932
933
                                            * useful for some emulators to change in run-time.
                                            *
                                            * max_width/max_height arguments are ignored and cannot be changed
trioan's avatar
trioan committed
934
                                            * with this call as this could potentially require a reinitialization or a
Alcaro's avatar
Alcaro committed
935
936
937
                                            * non-constant time operation.
                                            * If max_width/max_height are to be changed, SET_SYSTEM_AV_INFO is required.
                                            *
trioan's avatar
trioan committed
938
                                            * A frontend must guarantee that this environment call completes in
Alcaro's avatar
Alcaro committed
939
940
                                            * constant time.
                                            */
trioan's avatar
trioan committed
941
#define RETRO_ENVIRONMENT_GET_USERNAME 38
Alcaro's avatar
Alcaro committed
942
943
                                           /* const char **
                                            * Returns the specified username of the frontend, if specified by the user.
trioan's avatar
trioan committed
944
                                            * This username can be used as a nickname for a core that has online facilities
Alcaro's avatar
Alcaro committed
945
946
                                            * or any other mode where personalization of the user is desirable.
                                            * The returned value can be NULL.
trioan's avatar
trioan committed
947
                                            * If this environ callback is used by a core that requires a valid username,
Alcaro's avatar
Alcaro committed
948
949
950
951
952
953
954
                                            * a default username should be specified by the core.
                                            */
#define RETRO_ENVIRONMENT_GET_LANGUAGE 39
                                           /* unsigned * --
                                            * Returns the specified language of the frontend, if specified by the user.
                                            * It can be used by the core for localization purposes.
                                            */
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
#define RETRO_ENVIRONMENT_GET_CURRENT_SOFTWARE_FRAMEBUFFER (40 | RETRO_ENVIRONMENT_EXPERIMENTAL)
                                           /* struct retro_framebuffer * --
                                            * 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)
                                           /* const struct retro_hw_render_interface ** --
                                            * 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)
                                           /* const bool * --
                                            * 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.
                                            */
trioan's avatar
trioan committed
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
#define RETRO_ENVIRONMENT_SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE (43 | RETRO_ENVIRONMENT_EXPERIMENTAL)
                                           /* const struct retro_hw_render_context_negotiation_interface * --
                                            * 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
                                           /* uint64_t * --
                                            * 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)
                                           /* N/A (null) * --
                                            * 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)
                                           /* struct retro_vfs_interface_info * --
                                            * 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)
                                           /* struct retro_led_interface * --
                                            * 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)
                                           /* int * --
                                            * 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)
                                           /* struct retro_midi_interface ** --
                                            * Returns a MIDI interface that can be used for raw data I/O.
                                            */

#define RETRO_ENVIRONMENT_GET_FASTFORWARDING (49 | RETRO_ENVIRONMENT_EXPERIMENTAL)
                                            /* bool * --
                                            * Boolean value that indicates whether or not the frontend is in
                                            * fastforwarding mode.
                                            */

#define RETRO_ENVIRONMENT_GET_TARGET_REFRESH_RATE (50 | RETRO_ENVIRONMENT_EXPERIMENTAL)
                                            /* float * --
jdgleaver's avatar
jdgleaver committed
1094
                                            * Float value that lets us know what target refresh rate
trioan's avatar
trioan committed
1095
1096
                                            * is curently in use by the frontend.
                                            *
jdgleaver's avatar
jdgleaver committed
1097
                                            * The core can use the returned value to set an ideal
trioan's avatar
trioan committed
1098
1099
1100
1101
1102
1103
1104
                                            * refresh rate/framerate.
                                            */

#define RETRO_ENVIRONMENT_GET_INPUT_BITMASKS (51 | RETRO_ENVIRONMENT_EXPERIMENTAL)
                                            /* bool * --
                                            * Boolean value that indicates whether or not the frontend supports
                                            * input bitmasks being returned by retro_input_state_t. The advantage
jdgleaver's avatar
jdgleaver committed
1105
                                            * of this is that retro_input_state_t has to be only called once to
trioan's avatar
trioan committed
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
                                            * 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.
                                            */

#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.
                                            *
jdgleaver's avatar
jdgleaver committed
1124
                                            * If version is >= 1 however, core options may instead be set by
trioan's avatar
trioan committed
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
                                            * passing an array of retro_core_option_definition structs to
                                            * RETRO_ENVIRONMENT_SET_CORE_OPTIONS, or a 2D 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.
                                            */

#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.
jdgleaver's avatar
jdgleaver committed
1139
1140
                                            * This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION
                                            * returns an API version of >= 1.
trioan's avatar
trioan committed
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
                                            * 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 options 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.
jdgleaver's avatar
jdgleaver committed
1201
1202
                                            * This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION
                                            * returns an API version of >= 1.
trioan's avatar
trioan committed
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
                                            * 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.
                                            *
                                            * 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
                                            */
jdgleaver's avatar
jdgleaver committed
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337

#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.
                                            */

trioan's avatar
trioan committed
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
/* VFS functionality */

/* File paths:
 * File paths passed as parameters when using this API shall be well formed UNIX-style,
 * 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. */

/* Opaque file handle
 * Introduced in VFS API v1 */
struct retro_vfs_file_handle;

/* Opaque directory handle
 * Introduced in VFS API v3 */
struct retro_vfs_dir_handle;

/* File open flags
 * Introduced in VFS API v1 */
#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 */

/* 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. */
#define RETRO_VFS_FILE_ACCESS_HINT_NONE              (0)
/* Indicate that the file will be accessed many times. The frontend should aggressively cache everything. */
#define RETRO_VFS_FILE_ACCESS_HINT_FREQUENT_ACCESS   (1 << 0)

/* Seek positions */
#define RETRO_VFS_SEEK_POSITION_START    0
#define RETRO_VFS_SEEK_POSITION_CURRENT  1
#define RETRO_VFS_SEEK_POSITION_END      2

/* stat() result flags
 * Introduced in VFS API v3 */
#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)

/* Get path from opaque handle. Returns the exact same path passed to file_open when getting the handle
 * Introduced in VFS API v1 */
typedef const char *(RETRO_CALLCONV *retro_vfs_get_path_t)(struct retro_vfs_file_handle *stream);

/* Open a file for reading or writing. If path points to a directory, this will
 * fail. Returns the opaque file handle, or NULL for error.
 * Introduced in VFS API v1 */
typedef struct retro_vfs_file_handle *(RETRO_CALLCONV *retro_vfs_open_t)(const char *path, unsigned mode, unsigned hints);

/* Close the file and release its resources. Must be called if open_file returns non-NULL. Returns 0 on success, -1 on failure.
 * Whether the call succeeds ot not, the handle passed as parameter becomes invalid and should no longer be used.
 * Introduced in VFS API v1 */
typedef int (RETRO_CALLCONV *retro_vfs_close_t)(struct retro_vfs_file_handle *stream);

/* Return the size of the file in bytes, or -1 for error.
 * Introduced in VFS API v1 */
typedef int64_t (RETRO_CALLCONV *retro_vfs_size_t)(struct retro_vfs_file_handle *stream);

/* Truncate file to specified size. Returns 0 on success or -1 on error
 * Introduced in VFS API v2 */
typedef int64_t (RETRO_CALLCONV *retro_vfs_truncate_t)(struct retro_vfs_file_handle *stream, int64_t length);

/* Get the current read / write position for the file. Returns -1 for error.
 * Introduced in VFS API v1 */
typedef int64_t (RETRO_CALLCONV *retro_vfs_tell_t)(struct retro_vfs_file_handle *stream);

/* Set the current read/write position for the file. Returns the new position, -1 for error.
 * Introduced in VFS API v1 */
typedef int64_t (RETRO_CALLCONV *retro_vfs_seek_t)(struct retro_vfs_file_handle *stream, int64_t offset, int seek_position);

/* Read data from a file. Returns the number of bytes read, or -1 for error.
 * Introduced in VFS API v1 */
typedef int64_t (RETRO_CALLCONV *retro_vfs_read_t)(struct retro_vfs_file_handle *stream, void *s, uint64_t len);

/* Write data to a file. Returns the number of bytes written, or -1 for error.
 * Introduced in VFS API v1 */
typedef int64_t (RETRO_CALLCONV *retro_vfs_write_t)(struct retro_vfs_file_handle *stream, const void *s, uint64_t len);

/* Flush pending writes to file, if using buffered IO. Returns 0 on sucess, or -1 on failure.
 * Introduced in VFS API v1 */
typedef int (RETRO_CALLCONV *retro_vfs_flush_t)(struct retro_vfs_file_handle *stream);

/* Delete the specified file. Returns 0 on success, -1 on failure
 * Introduced in VFS API v1 */
typedef int (RETRO_CALLCONV *retro_vfs_remove_t)(const char *path);

/* Rename the specified file. Returns 0 on success, -1 on failure
 * Introduced in VFS API v1 */
typedef int (RETRO_CALLCONV *retro_vfs_rename_t)(const char *old_path, const char *new_path);

/* Stat the specified file. Retruns a bitmask of RETRO_VFS_STAT_* flags, none are set if path was not valid.
 * Additionally stores file size in given variable, unless NULL is given.
 * Introduced in VFS API v3 */
typedef int (RETRO_CALLCONV *retro_vfs_stat_t)(const char *path, int32_t *size);

/* Create the specified directory. Returns 0 on success, -1 on unknown failure, -2 if already exists.
 * Introduced in VFS API v3 */
typedef int (RETRO_CALLCONV *retro_vfs_mkdir_t)(const char *dir);

/* Open the specified directory for listing. Returns the opaque dir handle, or NULL for error.
 * Support for the include_hidden argument may vary depending on the platform.
 * Introduced in VFS API v3 */
typedef struct retro_vfs_dir_handle *(RETRO_CALLCONV *retro_vfs_opendir_t)(const char *dir, bool include_hidden);

/* Read the directory entry at the current position, and move the read pointer to the next position.
 * Returns true on success, false if already on the last entry.
 * Introduced in VFS API v3 */
typedef bool (RETRO_CALLCONV *retro_vfs_readdir_t)(struct retro_vfs_dir_handle *dirstream);

/* Get the name of the last entry read. Returns a string on success, or NULL for error.
 * The returned string pointer is valid until the next call to readdir or closedir.
 * Introduced in VFS API v3 */
typedef const char *(RETRO_CALLCONV *retro_vfs_dirent_get_name_t)(struct retro_vfs_dir_handle *dirstream);

/* Check if the last entry read was a directory. Returns true if it was, false otherwise (or on error).
 * Introduced in VFS API v3 */
typedef bool (RETRO_CALLCONV *retro_vfs_dirent_is_dir_t)(struct retro_vfs_dir_handle *dirstream);

/* Close the directory and release its resources. Must be called if opendir returns non-NULL. Returns 0 on success, -1 on failure.
 * Whether the call succeeds ot not, the handle passed as parameter becomes invalid and should no longer be used.
 * Introduced in VFS API v3 */
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,
    * front end will return false in the RETRO_ENVIRONMENT_GET_VFS_INTERFACE call
    * Introduced in VFS API v1 */
   uint32_t required_interface_version;

   /* Frontend writes interface pointer here. The frontend also sets the actual
    * version, must be at least required_interface_version.
    * Introduced in VFS API v1 */
   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
 * contain at least these fields. */
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.
 * Returns true if it's enabled, false otherwise. */
typedef bool (RETRO_CALLCONV *retro_midi_input_enabled_t)(void);

/* Retrieves the current state of the MIDI output.
 * Returns true if it's enabled, false otherwise */
typedef bool (RETRO_CALLCONV *retro_midi_output_enabled_t)(void);

/* Reads next byte from the input stream.
 * Returns true if byte is read, false otherwise. */
typedef bool (RETRO_CALLCONV *retro_midi_read_t)(uint8_t *byte);

/* Writes byte to the output stream.
 * 'delta_time' is in microseconds and represent time elapsed since previous write.
 * Returns true if byte is written, false otherwise. */
typedef bool (RETRO_CALLCONV *retro_midi_write_t)(uint8_t byte, uint32_t delta_time);

/* Flushes previously written data.
 * Returns true if successful, false otherwise. */
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;
<