Commit | Line | Data |
---|---|---|
7c830578 | 1 | /* Copyright (C) 2010-2014 The RetroArch team |
c40ab498 | 2 | * |
3 | * --------------------------------------------------------------------------------------- | |
4 | * The following license statement only applies to this libretro API header (libretro.h). | |
5 | * --------------------------------------------------------------------------------------- | |
6 | * | |
7 | * Permission is hereby granted, free of charge, | |
8 | * to any person obtaining a copy of this software and associated documentation files (the "Software"), | |
9 | * to deal in the Software without restriction, including without limitation the rights to | |
10 | * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, | |
11 | * and to permit persons to whom the Software is furnished to do so, subject to the following conditions: | |
12 | * | |
13 | * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. | |
14 | * | |
15 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, | |
16 | * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
17 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. | |
18 | * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, | |
19 | * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
20 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
21 | */ | |
22 | ||
38c2028e | 23 | #ifndef LIBRETRO_H__ |
24 | #define LIBRETRO_H__ | |
25 | ||
26 | #include <stdint.h> | |
27 | #include <stddef.h> | |
c19aba43 | 28 | #include <limits.h> |
38c2028e | 29 | |
30 | #ifdef __cplusplus | |
31 | extern "C" { | |
7c830578 A |
32 | #endif |
33 | ||
34 | #ifndef __cplusplus | |
35 | #if defined(_MSC_VER) && !defined(SN_TARGET_PS3) | |
36 | /* Hack applied for MSVC when compiling in C89 mode | |
37 | * as it isn't C99-compliant. */ | |
38c2028e | 38 | #define bool unsigned char |
39 | #define true 1 | |
40 | #define false 0 | |
41 | #else | |
42 | #include <stdbool.h> | |
43 | #endif | |
44 | #endif | |
45 | ||
7c830578 A |
46 | /* Used for checking API/ABI mismatches that can break libretro |
47 | * implementations. | |
48 | * It is not incremented for compatible changes to the API. | |
49 | */ | |
38c2028e | 50 | #define RETRO_API_VERSION 1 |
51 | ||
7c830578 A |
52 | /* |
53 | * Libretro's fundamental device abstractions. | |
54 | * | |
55 | * Libretro's input system consists of some standardized device types, | |
56 | * such as a joypad (with/without analog), mouse, keyboard, lightgun | |
57 | * and a pointer. | |
58 | * | |
59 | * The functionality of these devices are fixed, and individual cores | |
60 | * map their own concept of a controller to libretro's abstractions. | |
61 | * This makes it possible for frontends to map the abstract types to a | |
62 | * real input device, and not having to worry about binding input | |
63 | * correctly to arbitrary controller layouts. | |
64 | */ | |
65 | ||
66 | #define RETRO_DEVICE_TYPE_SHIFT 8 | |
67 | #define RETRO_DEVICE_MASK ((1 << RETRO_DEVICE_TYPE_SHIFT) - 1) | |
68 | #define RETRO_DEVICE_SUBCLASS(base, id) (((id + 1) << RETRO_DEVICE_TYPE_SHIFT) | base) | |
69 | ||
70 | /* Input disabled. */ | |
38c2028e | 71 | #define RETRO_DEVICE_NONE 0 |
c19aba43 | 72 | |
7c830578 A |
73 | /* The JOYPAD is called RetroPad. It is essentially a Super Nintendo |
74 | * controller, but with additional L2/R2/L3/R3 buttons, similar to a | |
75 | * PS1 DualShock. */ | |
38c2028e | 76 | #define RETRO_DEVICE_JOYPAD 1 |
c19aba43 | 77 | |
7c830578 A |
78 | /* The mouse is a simple mouse, similar to Super Nintendo's mouse. |
79 | * X and Y coordinates are reported relatively to last poll (poll callback). | |
80 | * It is up to the libretro implementation to keep track of where the mouse | |
81 | * pointer is supposed to be on the screen. | |
82 | * The frontend must make sure not to interfere with its own hardware | |
83 | * mouse pointer. | |
84 | */ | |
38c2028e | 85 | #define RETRO_DEVICE_MOUSE 2 |
c19aba43 | 86 | |
7c830578 A |
87 | /* KEYBOARD device lets one poll for raw key pressed. |
88 | * It is poll based, so input callback will return with the current | |
89 | * pressed state. | |
90 | * For event/text based keyboard input, see | |
91 | * RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK. | |
92 | */ | |
38c2028e | 93 | #define RETRO_DEVICE_KEYBOARD 3 |
c19aba43 | 94 | |
7c830578 A |
95 | /* Lightgun X/Y coordinates are reported relatively to last poll, |
96 | * similar to mouse. */ | |
38c2028e | 97 | #define RETRO_DEVICE_LIGHTGUN 4 |
c19aba43 | 98 | |
7c830578 A |
99 | /* The ANALOG device is an extension to JOYPAD (RetroPad). |
100 | * Similar to DualShock it adds two analog sticks. | |
101 | * This is treated as a separate device type as it returns values in the | |
102 | * full analog range of [-0x8000, 0x7fff]. Positive X axis is right. | |
103 | * Positive Y axis is down. | |
104 | * Only use ANALOG type when polling for analog values of the axes. | |
105 | */ | |
38c2028e | 106 | #define RETRO_DEVICE_ANALOG 5 |
107 | ||
7c830578 A |
108 | /* Abstracts the concept of a pointing mechanism, e.g. touch. |
109 | * This allows libretro to query in absolute coordinates where on the | |
110 | * screen a mouse (or something similar) is being placed. | |
111 | * For a touch centric device, coordinates reported are the coordinates | |
112 | * of the press. | |
113 | * | |
114 | * Coordinates in X and Y are reported as: | |
115 | * [-0x7fff, 0x7fff]: -0x7fff corresponds to the far left/top of the screen, | |
116 | * and 0x7fff corresponds to the far right/bottom of the screen. | |
117 | * The "screen" is here defined as area that is passed to the frontend and | |
118 | * later displayed on the monitor. | |
119 | * | |
120 | * The frontend is free to scale/resize this screen as it sees fit, however, | |
121 | * (X, Y) = (-0x7fff, -0x7fff) will correspond to the top-left pixel of the | |
122 | * game image, etc. | |
123 | * | |
124 | * To check if the pointer coordinates are valid (e.g. a touch display | |
125 | * actually being touched), PRESSED returns 1 or 0. | |
126 | * | |
127 | * If using a mouse on a desktop, PRESSED will usually correspond to the | |
128 | * left mouse button, but this is a frontend decision. | |
129 | * PRESSED will only return 1 if the pointer is inside the game screen. | |
130 | * | |
131 | * For multi-touch, the index variable can be used to successively query | |
132 | * more presses. | |
133 | * If index = 0 returns true for _PRESSED, coordinates can be extracted | |
134 | * with _X, _Y for index = 0. One can then query _PRESSED, _X, _Y with | |
135 | * index = 1, and so on. | |
136 | * Eventually _PRESSED will return false for an index. No further presses | |
137 | * are registered at this point. */ | |
23ea11bd | 138 | #define RETRO_DEVICE_POINTER 6 |
139 | ||
7c830578 A |
140 | /* Buttons for the RetroPad (JOYPAD). |
141 | * The placement of these is equivalent to placements on the | |
142 | * Super Nintendo controller. | |
143 | * L2/R2/L3/R3 buttons correspond to the PS1 DualShock. */ | |
38c2028e | 144 | #define RETRO_DEVICE_ID_JOYPAD_B 0 |
145 | #define RETRO_DEVICE_ID_JOYPAD_Y 1 | |
146 | #define RETRO_DEVICE_ID_JOYPAD_SELECT 2 | |
147 | #define RETRO_DEVICE_ID_JOYPAD_START 3 | |
148 | #define RETRO_DEVICE_ID_JOYPAD_UP 4 | |
149 | #define RETRO_DEVICE_ID_JOYPAD_DOWN 5 | |
150 | #define RETRO_DEVICE_ID_JOYPAD_LEFT 6 | |
151 | #define RETRO_DEVICE_ID_JOYPAD_RIGHT 7 | |
152 | #define RETRO_DEVICE_ID_JOYPAD_A 8 | |
153 | #define RETRO_DEVICE_ID_JOYPAD_X 9 | |
154 | #define RETRO_DEVICE_ID_JOYPAD_L 10 | |
155 | #define RETRO_DEVICE_ID_JOYPAD_R 11 | |
156 | #define RETRO_DEVICE_ID_JOYPAD_L2 12 | |
157 | #define RETRO_DEVICE_ID_JOYPAD_R2 13 | |
158 | #define RETRO_DEVICE_ID_JOYPAD_L3 14 | |
159 | #define RETRO_DEVICE_ID_JOYPAD_R3 15 | |
160 | ||
7c830578 | 161 | /* Index / Id values for ANALOG device. */ |
38c2028e | 162 | #define RETRO_DEVICE_INDEX_ANALOG_LEFT 0 |
163 | #define RETRO_DEVICE_INDEX_ANALOG_RIGHT 1 | |
164 | #define RETRO_DEVICE_ID_ANALOG_X 0 | |
165 | #define RETRO_DEVICE_ID_ANALOG_Y 1 | |
166 | ||
7c830578 A |
167 | /* Id values for MOUSE. */ |
168 | #define RETRO_DEVICE_ID_MOUSE_X 0 | |
169 | #define RETRO_DEVICE_ID_MOUSE_Y 1 | |
170 | #define RETRO_DEVICE_ID_MOUSE_LEFT 2 | |
171 | #define RETRO_DEVICE_ID_MOUSE_RIGHT 3 | |
172 | #define RETRO_DEVICE_ID_MOUSE_WHEELUP 4 | |
173 | #define RETRO_DEVICE_ID_MOUSE_WHEELDOWN 5 | |
174 | #define RETRO_DEVICE_ID_MOUSE_MIDDLE 6 | |
38c2028e | 175 | |
7c830578 | 176 | /* Id values for LIGHTGUN types. */ |
38c2028e | 177 | #define RETRO_DEVICE_ID_LIGHTGUN_X 0 |
178 | #define RETRO_DEVICE_ID_LIGHTGUN_Y 1 | |
179 | #define RETRO_DEVICE_ID_LIGHTGUN_TRIGGER 2 | |
180 | #define RETRO_DEVICE_ID_LIGHTGUN_CURSOR 3 | |
181 | #define RETRO_DEVICE_ID_LIGHTGUN_TURBO 4 | |
182 | #define RETRO_DEVICE_ID_LIGHTGUN_PAUSE 5 | |
183 | #define RETRO_DEVICE_ID_LIGHTGUN_START 6 | |
184 | ||
7c830578 | 185 | /* Id values for POINTER. */ |
23ea11bd | 186 | #define RETRO_DEVICE_ID_POINTER_X 0 |
187 | #define RETRO_DEVICE_ID_POINTER_Y 1 | |
188 | #define RETRO_DEVICE_ID_POINTER_PRESSED 2 | |
189 | ||
7c830578 | 190 | /* Returned from retro_get_region(). */ |
38c2028e | 191 | #define RETRO_REGION_NTSC 0 |
192 | #define RETRO_REGION_PAL 1 | |
193 | ||
7c830578 A |
194 | /* Id values for LANGUAGE */ |
195 | enum retro_language | |
196 | { | |
197 | RETRO_LANGUAGE_ENGLISH = 0, | |
198 | RETRO_LANGUAGE_JAPANESE = 1, | |
199 | RETRO_LANGUAGE_FRENCH = 2, | |
200 | RETRO_LANGUAGE_SPANISH = 3, | |
201 | RETRO_LANGUAGE_GERMAN = 4, | |
202 | RETRO_LANGUAGE_ITALIAN = 5, | |
203 | RETRO_LANGUAGE_DUTCH = 6, | |
204 | RETRO_LANGUAGE_PORTUGUESE = 7, | |
205 | RETRO_LANGUAGE_RUSSIAN = 8, | |
206 | RETRO_LANGUAGE_KOREAN = 9, | |
207 | RETRO_LANGUAGE_CHINESE_TRADITIONAL = 10, | |
208 | RETRO_LANGUAGE_CHINESE_SIMPLIFIED = 11, | |
209 | RETRO_LANGUAGE_LAST, | |
210 | ||
211 | /* Ensure sizeof(enum) == sizeof(int) */ | |
212 | RETRO_LANGUAGE_DUMMY = INT_MAX | |
213 | }; | |
214 | ||
215 | /* Passed to retro_get_memory_data/size(). | |
216 | * If the memory type doesn't apply to the | |
217 | * implementation NULL/0 can be returned. | |
218 | */ | |
38c2028e | 219 | #define RETRO_MEMORY_MASK 0xff |
c19aba43 | 220 | |
7c830578 A |
221 | /* Regular save RAM. This RAM is usually found on a game cartridge, |
222 | * backed up by a battery. | |
223 | * If save game data is too complex for a single memory buffer, | |
224 | * the SAVE_DIRECTORY (preferably) or SYSTEM_DIRECTORY environment | |
225 | * callback can be used. */ | |
38c2028e | 226 | #define RETRO_MEMORY_SAVE_RAM 0 |
c19aba43 | 227 | |
7c830578 A |
228 | /* Some games have a built-in clock to keep track of time. |
229 | * This memory is usually just a couple of bytes to keep track of time. | |
230 | */ | |
38c2028e | 231 | #define RETRO_MEMORY_RTC 1 |
c19aba43 | 232 | |
7c830578 | 233 | /* System ram lets a frontend peek into a game systems main RAM. */ |
38c2028e | 234 | #define RETRO_MEMORY_SYSTEM_RAM 2 |
c19aba43 | 235 | |
7c830578 | 236 | /* Video ram lets a frontend peek into a game systems video RAM (VRAM). */ |
38c2028e | 237 | #define RETRO_MEMORY_VIDEO_RAM 3 |
238 | ||
7c830578 | 239 | /* Keysyms used for ID in input state callback when polling RETRO_KEYBOARD. */ |
c19aba43 TK |
240 | enum retro_key |
241 | { | |
242 | RETROK_UNKNOWN = 0, | |
243 | RETROK_FIRST = 0, | |
244 | RETROK_BACKSPACE = 8, | |
245 | RETROK_TAB = 9, | |
246 | RETROK_CLEAR = 12, | |
247 | RETROK_RETURN = 13, | |
248 | RETROK_PAUSE = 19, | |
249 | RETROK_ESCAPE = 27, | |
250 | RETROK_SPACE = 32, | |
251 | RETROK_EXCLAIM = 33, | |
252 | RETROK_QUOTEDBL = 34, | |
253 | RETROK_HASH = 35, | |
254 | RETROK_DOLLAR = 36, | |
255 | RETROK_AMPERSAND = 38, | |
256 | RETROK_QUOTE = 39, | |
257 | RETROK_LEFTPAREN = 40, | |
258 | RETROK_RIGHTPAREN = 41, | |
259 | RETROK_ASTERISK = 42, | |
260 | RETROK_PLUS = 43, | |
261 | RETROK_COMMA = 44, | |
262 | RETROK_MINUS = 45, | |
263 | RETROK_PERIOD = 46, | |
264 | RETROK_SLASH = 47, | |
265 | RETROK_0 = 48, | |
266 | RETROK_1 = 49, | |
267 | RETROK_2 = 50, | |
268 | RETROK_3 = 51, | |
269 | RETROK_4 = 52, | |
270 | RETROK_5 = 53, | |
271 | RETROK_6 = 54, | |
272 | RETROK_7 = 55, | |
273 | RETROK_8 = 56, | |
274 | RETROK_9 = 57, | |
275 | RETROK_COLON = 58, | |
276 | RETROK_SEMICOLON = 59, | |
277 | RETROK_LESS = 60, | |
278 | RETROK_EQUALS = 61, | |
279 | RETROK_GREATER = 62, | |
280 | RETROK_QUESTION = 63, | |
281 | RETROK_AT = 64, | |
282 | RETROK_LEFTBRACKET = 91, | |
283 | RETROK_BACKSLASH = 92, | |
284 | RETROK_RIGHTBRACKET = 93, | |
285 | RETROK_CARET = 94, | |
286 | RETROK_UNDERSCORE = 95, | |
287 | RETROK_BACKQUOTE = 96, | |
288 | RETROK_a = 97, | |
289 | RETROK_b = 98, | |
290 | RETROK_c = 99, | |
291 | RETROK_d = 100, | |
292 | RETROK_e = 101, | |
293 | RETROK_f = 102, | |
294 | RETROK_g = 103, | |
295 | RETROK_h = 104, | |
296 | RETROK_i = 105, | |
297 | RETROK_j = 106, | |
298 | RETROK_k = 107, | |
299 | RETROK_l = 108, | |
300 | RETROK_m = 109, | |
301 | RETROK_n = 110, | |
302 | RETROK_o = 111, | |
303 | RETROK_p = 112, | |
304 | RETROK_q = 113, | |
305 | RETROK_r = 114, | |
306 | RETROK_s = 115, | |
307 | RETROK_t = 116, | |
308 | RETROK_u = 117, | |
309 | RETROK_v = 118, | |
310 | RETROK_w = 119, | |
311 | RETROK_x = 120, | |
312 | RETROK_y = 121, | |
313 | RETROK_z = 122, | |
314 | RETROK_DELETE = 127, | |
315 | ||
316 | RETROK_KP0 = 256, | |
317 | RETROK_KP1 = 257, | |
318 | RETROK_KP2 = 258, | |
319 | RETROK_KP3 = 259, | |
320 | RETROK_KP4 = 260, | |
321 | RETROK_KP5 = 261, | |
322 | RETROK_KP6 = 262, | |
323 | RETROK_KP7 = 263, | |
324 | RETROK_KP8 = 264, | |
325 | RETROK_KP9 = 265, | |
326 | RETROK_KP_PERIOD = 266, | |
327 | RETROK_KP_DIVIDE = 267, | |
328 | RETROK_KP_MULTIPLY = 268, | |
329 | RETROK_KP_MINUS = 269, | |
330 | RETROK_KP_PLUS = 270, | |
331 | RETROK_KP_ENTER = 271, | |
332 | RETROK_KP_EQUALS = 272, | |
333 | ||
334 | RETROK_UP = 273, | |
335 | RETROK_DOWN = 274, | |
336 | RETROK_RIGHT = 275, | |
337 | RETROK_LEFT = 276, | |
338 | RETROK_INSERT = 277, | |
339 | RETROK_HOME = 278, | |
340 | RETROK_END = 279, | |
341 | RETROK_PAGEUP = 280, | |
342 | RETROK_PAGEDOWN = 281, | |
343 | ||
344 | RETROK_F1 = 282, | |
345 | RETROK_F2 = 283, | |
346 | RETROK_F3 = 284, | |
347 | RETROK_F4 = 285, | |
348 | RETROK_F5 = 286, | |
349 | RETROK_F6 = 287, | |
350 | RETROK_F7 = 288, | |
351 | RETROK_F8 = 289, | |
352 | RETROK_F9 = 290, | |
353 | RETROK_F10 = 291, | |
354 | RETROK_F11 = 292, | |
355 | RETROK_F12 = 293, | |
356 | RETROK_F13 = 294, | |
357 | RETROK_F14 = 295, | |
358 | RETROK_F15 = 296, | |
359 | ||
360 | RETROK_NUMLOCK = 300, | |
361 | RETROK_CAPSLOCK = 301, | |
362 | RETROK_SCROLLOCK = 302, | |
363 | RETROK_RSHIFT = 303, | |
364 | RETROK_LSHIFT = 304, | |
365 | RETROK_RCTRL = 305, | |
366 | RETROK_LCTRL = 306, | |
367 | RETROK_RALT = 307, | |
368 | RETROK_LALT = 308, | |
369 | RETROK_RMETA = 309, | |
370 | RETROK_LMETA = 310, | |
371 | RETROK_LSUPER = 311, | |
372 | RETROK_RSUPER = 312, | |
373 | RETROK_MODE = 313, | |
374 | RETROK_COMPOSE = 314, | |
375 | ||
376 | RETROK_HELP = 315, | |
377 | RETROK_PRINT = 316, | |
378 | RETROK_SYSREQ = 317, | |
379 | RETROK_BREAK = 318, | |
380 | RETROK_MENU = 319, | |
381 | RETROK_POWER = 320, | |
382 | RETROK_EURO = 321, | |
383 | RETROK_UNDO = 322, | |
384 | ||
23ea11bd | 385 | RETROK_LAST, |
386 | ||
7c830578 | 387 | RETROK_DUMMY = INT_MAX /* Ensure sizeof(enum) == sizeof(int) */ |
23ea11bd | 388 | }; |
389 | ||
390 | enum retro_mod | |
391 | { | |
392 | RETROKMOD_NONE = 0x0000, | |
393 | ||
394 | RETROKMOD_SHIFT = 0x01, | |
395 | RETROKMOD_CTRL = 0x02, | |
396 | RETROKMOD_ALT = 0x04, | |
397 | RETROKMOD_META = 0x08, | |
398 | ||
399 | RETROKMOD_NUMLOCK = 0x10, | |
400 | RETROKMOD_CAPSLOCK = 0x20, | |
401 | RETROKMOD_SCROLLOCK = 0x40, | |
402 | ||
7c830578 | 403 | RETROKMOD_DUMMY = INT_MAX /* Ensure sizeof(enum) == sizeof(int) */ |
c19aba43 | 404 | }; |
38c2028e | 405 | |
7c830578 A |
406 | /* If set, this call is not part of the public libretro API yet. It can |
407 | * change or be removed at any time. */ | |
72f68e8c | 408 | #define RETRO_ENVIRONMENT_EXPERIMENTAL 0x10000 |
7c830578 | 409 | /* Environment callback to be used internally in frontend. */ |
c40ab498 | 410 | #define RETRO_ENVIRONMENT_PRIVATE 0x20000 |
23ea11bd | 411 | |
7c830578 A |
412 | /* Environment commands. */ |
413 | #define RETRO_ENVIRONMENT_SET_ROTATION 1 /* const unsigned * -- | |
414 | * Sets screen rotation of graphics. | |
415 | * Is only implemented if rotation can be accelerated by hardware. | |
416 | * Valid values are 0, 1, 2, 3, which rotates screen by 0, 90, 180, | |
417 | * 270 degrees counter-clockwise respectively. | |
418 | */ | |
419 | #define RETRO_ENVIRONMENT_GET_OVERSCAN 2 /* bool * -- | |
420 | * Boolean value whether or not the implementation should use overscan, | |
421 | * or crop away overscan. | |
422 | */ | |
423 | #define RETRO_ENVIRONMENT_GET_CAN_DUPE 3 /* bool * -- | |
424 | * Boolean value whether or not frontend supports frame duping, | |
425 | * passing NULL to video frame callback. | |
426 | */ | |
427 | ||
428 | /* Environ 4, 5 are no longer supported (GET_VARIABLE / SET_VARIABLES), | |
429 | * and reserved to avoid possible ABI clash. | |
430 | */ | |
431 | ||
432 | #define RETRO_ENVIRONMENT_SET_MESSAGE 6 /* const struct retro_message * -- | |
433 | * Sets a message to be displayed in implementation-specific manner | |
434 | * for a certain amount of 'frames'. | |
435 | * Should not be used for trivial messages, which should simply be | |
436 | * logged via RETRO_ENVIRONMENT_GET_LOG_INTERFACE (or as a | |
437 | * fallback, stderr). | |
438 | */ | |
439 | #define RETRO_ENVIRONMENT_SHUTDOWN 7 /* N/A (NULL) -- | |
440 | * Requests the frontend to shutdown. | |
441 | * Should only be used if game has a specific | |
442 | * way to shutdown the game from a menu item or similar. | |
443 | */ | |
38c2028e | 444 | #define RETRO_ENVIRONMENT_SET_PERFORMANCE_LEVEL 8 |
7c830578 A |
445 | /* const unsigned * -- |
446 | * Gives a hint to the frontend how demanding this implementation | |
447 | * is on a system. E.g. reporting a level of 2 means | |
448 | * this implementation should run decently on all frontends | |
449 | * of level 2 and up. | |
450 | * | |
451 | * It can be used by the frontend to potentially warn | |
452 | * about too demanding implementations. | |
453 | * | |
454 | * The levels are "floating". | |
455 | * | |
456 | * This function can be called on a per-game basis, | |
457 | * as certain games an implementation can play might be | |
458 | * particularly demanding. | |
459 | * If called, it should be called in retro_load_game(). | |
460 | */ | |
38c2028e | 461 | #define RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY 9 |
7c830578 A |
462 | /* const char ** -- |
463 | * Returns the "system" directory of the frontend. | |
464 | * This directory can be used to store system specific | |
465 | * content such as BIOSes, configuration data, etc. | |
466 | * The returned value can be NULL. | |
467 | * If so, no such directory is defined, | |
468 | * and it's up to the implementation to find a suitable directory. | |
469 | * | |
470 | * NOTE: Some cores used this folder also for "save" data such as | |
471 | * memory cards, etc, for lack of a better place to put it. | |
472 | * This is now discouraged, and if possible, cores should try to | |
473 | * use the new GET_SAVE_DIRECTORY. | |
474 | */ | |
38c2028e | 475 | #define RETRO_ENVIRONMENT_SET_PIXEL_FORMAT 10 |
7c830578 A |
476 | /* const enum retro_pixel_format * -- |
477 | * Sets the internal pixel format used by the implementation. | |
478 | * The default pixel format is RETRO_PIXEL_FORMAT_0RGB1555. | |
479 | * This pixel format however, is deprecated (see enum retro_pixel_format). | |
480 | * If the call returns false, the frontend does not support this pixel | |
481 | * format. | |
482 | * | |
483 | * This function should be called inside retro_load_game() or | |
484 | * retro_get_system_av_info(). | |
485 | */ | |
c19aba43 | 486 | #define RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS 11 |
7c830578 A |
487 | /* const struct retro_input_descriptor * -- |
488 | * Sets an array of retro_input_descriptors. | |
489 | * It is up to the frontend to present this in a usable way. | |
490 | * The array is terminated by retro_input_descriptor::description | |
491 | * being set to NULL. | |
492 | * This function can be called at any time, but it is recommended | |
493 | * to call it as early as possible. | |
494 | */ | |
23ea11bd | 495 | #define RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK 12 |
7c830578 A |
496 | /* const struct retro_keyboard_callback * -- |
497 | * Sets a callback function used to notify core about keyboard events. | |
498 | */ | |
23ea11bd | 499 | #define RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE 13 |
7c830578 A |
500 | /* const struct retro_disk_control_callback * -- |
501 | * Sets an interface which frontend can use to eject and insert | |
502 | * disk images. | |
503 | * This is used for games which consist of multiple images and | |
504 | * must be manually swapped out by the user (e.g. PSX). | |
505 | */ | |
c40ab498 | 506 | #define RETRO_ENVIRONMENT_SET_HW_RENDER 14 |
7c830578 A |
507 | /* struct retro_hw_render_callback * -- |
508 | * Sets an interface to let a libretro core render with | |
509 | * hardware acceleration. | |
510 | * Should be called in retro_load_game(). | |
511 | * If successful, libretro cores will be able to render to a | |
512 | * frontend-provided framebuffer. | |
513 | * The size of this framebuffer will be at least as large as | |
514 | * max_width/max_height provided in get_av_info(). | |
515 | * If HW rendering is used, pass only RETRO_HW_FRAME_BUFFER_VALID or | |
516 | * NULL to retro_video_refresh_t. | |
517 | */ | |
72f68e8c | 518 | #define RETRO_ENVIRONMENT_GET_VARIABLE 15 |
7c830578 A |
519 | /* struct retro_variable * -- |
520 | * Interface to acquire user-defined information from environment | |
521 | * that cannot feasibly be supported in a multi-system way. | |
522 | * 'key' should be set to a key which has already been set by | |
523 | * SET_VARIABLES. | |
524 | * 'data' will be set to a value or NULL. | |
525 | */ | |
72f68e8c | 526 | #define RETRO_ENVIRONMENT_SET_VARIABLES 16 |
7c830578 A |
527 | /* const struct retro_variable * -- |
528 | * Allows an implementation to signal the environment | |
529 | * which variables it might want to check for later using | |
530 | * GET_VARIABLE. | |
531 | * This allows the frontend to present these variables to | |
532 | * a user dynamically. | |
533 | * This should be called as early as possible (ideally in | |
534 | * retro_set_environment). | |
535 | * | |
536 | * 'data' points to an array of retro_variable structs | |
537 | * terminated by a { NULL, NULL } element. | |
538 | * retro_variable::key should be namespaced to not collide | |
539 | * with other implementations' keys. E.g. A core called | |
540 | * 'foo' should use keys named as 'foo_option'. | |
541 | * retro_variable::value should contain a human readable | |
542 | * description of the key as well as a '|' delimited list | |
543 | * of expected values. | |
544 | * | |
545 | * The number of possible options should be very limited, | |
546 | * i.e. it should be feasible to cycle through options | |
547 | * without a keyboard. | |
548 | * | |
549 | * First entry should be treated as a default. | |
550 | * | |
551 | * Example entry: | |
552 | * { "foo_option", "Speed hack coprocessor X; false|true" } | |
553 | * | |
554 | * Text before first ';' is description. This ';' must be | |
555 | * followed by a space, and followed by a list of possible | |
556 | * values split up with '|'. | |
557 | * | |
558 | * Only strings are operated on. The possible values will | |
559 | * generally be displayed and stored as-is by the frontend. | |
560 | */ | |
72f68e8c | 561 | #define RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE 17 |
7c830578 A |
562 | /* bool * -- |
563 | * Result is set to true if some variables are updated by | |
564 | * frontend since last call to RETRO_ENVIRONMENT_GET_VARIABLE. | |
565 | * Variables should be queried with GET_VARIABLE. | |
566 | */ | |
e268a47e | 567 | #define RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME 18 |
7c830578 A |
568 | /* const bool * -- |
569 | * If true, the libretro implementation supports calls to | |
570 | * retro_load_game() with NULL as argument. | |
571 | * Used by cores which can run without particular game data. | |
572 | * This should be called within retro_set_environment() only. | |
573 | */ | |
c40ab498 | 574 | #define RETRO_ENVIRONMENT_GET_LIBRETRO_PATH 19 |
7c830578 A |
575 | /* const char ** -- |
576 | * Retrieves the absolute path from where this libretro | |
577 | * implementation was loaded. | |
578 | * NULL is returned if the libretro was loaded statically | |
579 | * (i.e. linked statically to frontend), or if the path cannot be | |
580 | * determined. | |
581 | * Mostly useful in cooperation with SET_SUPPORT_NO_GAME as assets can | |
582 | * be loaded without ugly hacks. | |
583 | */ | |
584 | ||
585 | /* Environment 20 was an obsolete version of SET_AUDIO_CALLBACK. | |
586 | * It was not used by any known core at the time, | |
587 | * and was removed from the API. */ | |
c40ab498 | 588 | #define RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK 22 |
7c830578 A |
589 | /* const struct retro_audio_callback * -- |
590 | * Sets an interface which is used to notify a libretro core about audio | |
591 | * being available for writing. | |
592 | * The callback can be called from any thread, so a core using this must | |
593 | * have a thread safe audio implementation. | |
594 | * It is intended for games where audio and video are completely | |
595 | * asynchronous and audio can be generated on the fly. | |
596 | * This interface is not recommended for use with emulators which have | |
597 | * highly synchronous audio. | |
598 | * | |
599 | * The callback only notifies about writability; the libretro core still | |
600 | * has to call the normal audio callbacks | |
601 | * to write audio. The audio callbacks must be called from within the | |
602 | * notification callback. | |
603 | * The amount of audio data to write is up to the implementation. | |
604 | * Generally, the audio callback will be called continously in a loop. | |
605 | * | |
606 | * Due to thread safety guarantees and lack of sync between audio and | |
607 | * video, a frontend can selectively disallow this interface based on | |
608 | * internal configuration. A core using this interface must also | |
609 | * implement the "normal" audio interface. | |
610 | * | |
611 | * A libretro core using SET_AUDIO_CALLBACK should also make use of | |
612 | * SET_FRAME_TIME_CALLBACK. | |
613 | */ | |
c40ab498 | 614 | #define RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK 21 |
7c830578 A |
615 | /* const struct retro_frame_time_callback * -- |
616 | * Lets the core know how much time has passed since last | |
617 | * invocation of retro_run(). | |
618 | * The frontend can tamper with the timing to fake fast-forward, | |
619 | * slow-motion, frame stepping, etc. | |
620 | * In this case the delta time will use the reference value | |
621 | * in frame_time_callback.. | |
622 | */ | |
c40ab498 | 623 | #define RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE 23 |
7c830578 A |
624 | /* struct retro_rumble_interface * -- |
625 | * Gets an interface which is used by a libretro core to set | |
626 | * state of rumble motors in controllers. | |
627 | * A strong and weak motor is supported, and they can be | |
628 | * controlled indepedently. | |
629 | */ | |
c40ab498 | 630 | #define RETRO_ENVIRONMENT_GET_INPUT_DEVICE_CAPABILITIES 24 |
7c830578 A |
631 | /* uint64_t * -- |
632 | * Gets a bitmask telling which device type are expected to be | |
633 | * handled properly in a call to retro_input_state_t. | |
634 | * Devices which are not handled or recognized always return | |
635 | * 0 in retro_input_state_t. | |
636 | * Example bitmask: caps = (1 << RETRO_DEVICE_JOYPAD) | (1 << RETRO_DEVICE_ANALOG). | |
637 | * Should only be called in retro_run(). | |
638 | */ | |
c40ab498 | 639 | #define RETRO_ENVIRONMENT_GET_SENSOR_INTERFACE (25 | RETRO_ENVIRONMENT_EXPERIMENTAL) |
7c830578 A |
640 | /* struct retro_sensor_interface * -- |
641 | * Gets access to the sensor interface. | |
642 | * The purpose of this interface is to allow | |
643 | * setting state related to sensors such as polling rate, | |
644 | * enabling/disable it entirely, etc. | |
645 | * Reading sensor state is done via the normal | |
646 | * input_state_callback API. | |
647 | */ | |
c40ab498 | 648 | #define RETRO_ENVIRONMENT_GET_CAMERA_INTERFACE (26 | RETRO_ENVIRONMENT_EXPERIMENTAL) |
7c830578 A |
649 | /* struct retro_camera_callback * -- |
650 | * Gets an interface to a video camera driver. | |
651 | * A libretro core can use this interface to get access to a | |
652 | * video camera. | |
653 | * New video frames are delivered in a callback in same | |
654 | * thread as retro_run(). | |
655 | * | |
656 | * GET_CAMERA_INTERFACE should be called in retro_load_game(). | |
657 | * | |
658 | * Depending on the camera implementation used, camera frames | |
659 | * will be delivered as a raw framebuffer, | |
660 | * or as an OpenGL texture directly. | |
661 | * | |
662 | * The core has to tell the frontend here which types of | |
663 | * buffers can be handled properly. | |
664 | * An OpenGL texture can only be handled when using a | |
665 | * libretro GL core (SET_HW_RENDER). | |
666 | * It is recommended to use a libretro GL core when | |
667 | * using camera interface. | |
668 | * | |
669 | * The camera is not started automatically. The retrieved start/stop | |
670 | * functions must be used to explicitly | |
671 | * start and stop the camera driver. | |
672 | */ | |
c40ab498 | 673 | #define RETRO_ENVIRONMENT_GET_LOG_INTERFACE 27 |
7c830578 A |
674 | /* struct retro_log_callback * -- |
675 | * Gets an interface for logging. This is useful for | |
676 | * logging in a cross-platform way | |
677 | * as certain platforms cannot use use stderr for logging. | |
678 | * It also allows the frontend to | |
679 | * show logging information in a more suitable way. | |
680 | * If this interface is not used, libretro cores should | |
681 | * log to stderr as desired. | |
682 | */ | |
c40ab498 | 683 | #define RETRO_ENVIRONMENT_GET_PERF_INTERFACE 28 |
7c830578 A |
684 | /* struct retro_perf_callback * -- |
685 | * Gets an interface for performance counters. This is useful | |
686 | * for performance logging in a cross-platform way and for detecting | |
687 | * architecture-specific features, such as SIMD support. | |
688 | */ | |
689 | #define RETRO_ENVIRONMENT_GET_LOCATION_INTERFACE 29 | |
690 | /* struct retro_location_callback * -- | |
691 | * Gets access to the location interface. | |
692 | * The purpose of this interface is to be able to retrieve | |
693 | * location-based information from the host device, | |
694 | * such as current latitude / longitude. | |
695 | */ | |
696 | #define RETRO_ENVIRONMENT_GET_CONTENT_DIRECTORY 30 | |
697 | /* const char ** -- | |
698 | * Returns the "content" directory of the frontend. | |
699 | * This directory can be used to store specific assets that the | |
700 | * core relies upon, such as art assets, | |
701 | * input data, etc etc. | |
702 | * The returned value can be NULL. | |
703 | * If so, no such directory is defined, | |
704 | * and it's up to the implementation to find a suitable directory. | |
705 | */ | |
706 | #define RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY 31 | |
707 | /* const char ** -- | |
708 | * Returns the "save" directory of the frontend. | |
709 | * This directory can be used to store SRAM, memory cards, | |
710 | * high scores, etc, if the libretro core | |
711 | * cannot use the regular memory interface (retro_get_memory_data()). | |
712 | * | |
713 | * NOTE: libretro cores used to check GET_SYSTEM_DIRECTORY for | |
714 | * similar things before. | |
715 | * They should still check GET_SYSTEM_DIRECTORY if they want to | |
716 | * be backwards compatible. | |
717 | * The path here can be NULL. It should only be non-NULL if the | |
718 | * frontend user has set a specific save path. | |
719 | */ | |
720 | #define RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO 32 | |
721 | /* const struct retro_system_av_info * -- | |
722 | * Sets a new av_info structure. This can only be called from | |
723 | * within retro_run(). | |
724 | * This should *only* be used if the core is completely altering the | |
725 | * internal resolutions, aspect ratios, timings, sampling rate, etc. | |
726 | * Calling this can require a full reinitialization of video/audio | |
727 | * drivers in the frontend, | |
728 | * | |
729 | * so it is important to call it very sparingly, and usually only with | |
730 | * the users explicit consent. | |
731 | * An eventual driver reinitialize will happen so that video and | |
732 | * audio callbacks | |
733 | * happening after this call within the same retro_run() call will | |
734 | * target the newly initialized driver. | |
735 | * | |
736 | * This callback makes it possible to support configurable resolutions | |
737 | * in games, which can be useful to | |
738 | * avoid setting the "worst case" in max_width/max_height. | |
739 | * | |
740 | * ***HIGHLY RECOMMENDED*** Do not call this callback every time | |
741 | * resolution changes in an emulator core if it's | |
742 | * expected to be a temporary change, for the reasons of possible | |
743 | * driver reinitialization. | |
744 | * This call is not a free pass for not trying to provide | |
745 | * correct values in retro_get_system_av_info(). If you need to change | |
746 | * things like aspect ratio or nominal width/height, | |
747 | * use RETRO_ENVIRONMENT_SET_GEOMETRY, which is a softer variant | |
748 | * of SET_SYSTEM_AV_INFO. | |
749 | * | |
750 | * If this returns false, the frontend does not acknowledge a | |
751 | * changed av_info struct. | |
752 | */ | |
753 | #define RETRO_ENVIRONMENT_SET_PROC_ADDRESS_CALLBACK 33 | |
754 | /* const struct retro_get_proc_address_interface * -- | |
755 | * Allows a libretro core to announce support for the | |
756 | * get_proc_address() interface. | |
757 | * This interface allows for a standard way to extend libretro where | |
758 | * use of environment calls are too indirect, | |
759 | * e.g. for cases where the frontend wants to call directly into the core. | |
760 | * | |
761 | * If a core wants to expose this interface, SET_PROC_ADDRESS_CALLBACK | |
762 | * **MUST** be called from within retro_set_environment(). | |
763 | */ | |
764 | #define RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO 34 | |
765 | /* const struct retro_subsystem_info * -- | |
766 | * This environment call introduces the concept of libretro "subsystems". | |
767 | * A subsystem is a variant of a libretro core which supports | |
768 | * different kinds of games. | |
769 | * The purpose of this is to support e.g. emulators which might | |
770 | * have special needs, e.g. Super Nintendo's Super GameBoy, Sufami Turbo. | |
771 | * It can also be used to pick among subsystems in an explicit way | |
772 | * if the libretro implementation is a multi-system emulator itself. | |
773 | * | |
774 | * Loading a game via a subsystem is done with retro_load_game_special(), | |
775 | * and this environment call allows a libretro core to expose which | |
776 | * subsystems are supported for use with retro_load_game_special(). | |
777 | * A core passes an array of retro_game_special_info which is terminated | |
778 | * with a zeroed out retro_game_special_info struct. | |
779 | * | |
780 | * If a core wants to use this functionality, SET_SUBSYSTEM_INFO | |
781 | * **MUST** be called from within retro_set_environment(). | |
782 | */ | |
783 | #define RETRO_ENVIRONMENT_SET_CONTROLLER_INFO 35 | |
784 | /* const struct retro_controller_info * -- | |
785 | * This environment call lets a libretro core tell the frontend | |
786 | * which controller types are recognized in calls to | |
787 | * retro_set_controller_port_device(). | |
788 | * | |
789 | * Some emulators such as Super Nintendo | |
790 | * support multiple lightgun types which must be specifically | |
791 | * selected from. | |
792 | * It is therefore sometimes necessary for a frontend to be able | |
793 | * to tell the core about a special kind of input device which is | |
794 | * not covered by the libretro input API. | |
795 | * | |
796 | * In order for a frontend to understand the workings of an input device, | |
797 | * it must be a specialized type | |
798 | * of the generic device types already defined in the libretro API. | |
799 | * | |
800 | * Which devices are supported can vary per input port. | |
801 | * The core must pass an array of const struct retro_controller_info which | |
802 | * is terminated with a blanked out struct. Each element of the struct | |
803 | * corresponds to an ascending port index to | |
804 | * retro_set_controller_port_device(). | |
805 | * Even if special device types are set in the libretro core, | |
806 | * libretro should only poll input based on the base input device types. | |
807 | */ | |
808 | #define RETRO_ENVIRONMENT_SET_MEMORY_MAPS (36 | RETRO_ENVIRONMENT_EXPERIMENTAL) | |
809 | /* const struct retro_memory_map * -- | |
810 | * This environment call lets a libretro core tell the frontend | |
811 | * about the memory maps this core emulates. | |
812 | * This can be used to implement, for example, cheats in a core-agnostic way. | |
813 | * | |
814 | * Should only be used by emulators; it doesn't make much sense for | |
815 | * anything else. | |
816 | * It is recommended to expose all relevant pointers through | |
817 | * retro_get_memory_* as well. | |
818 | * | |
819 | * Can be called from retro_init and retro_load_game. | |
820 | */ | |
821 | #define RETRO_ENVIRONMENT_SET_GEOMETRY 37 | |
822 | /* const struct retro_game_geometry * -- | |
823 | * This environment call is similar to SET_SYSTEM_AV_INFO for changing | |
824 | * video parameters, but provides a guarantee that drivers will not be | |
825 | * reinitialized. | |
826 | * This can only be called from within retro_run(). | |
827 | * | |
828 | * The purpose of this call is to allow a core to alter nominal | |
829 | * width/heights as well as aspect ratios on-the-fly, which can be | |
830 | * useful for some emulators to change in run-time. | |
831 | * | |
832 | * max_width/max_height arguments are ignored and cannot be changed | |
833 | * with this call as this could potentially require a reinitialization or a | |
834 | * non-constant time operation. | |
835 | * If max_width/max_height are to be changed, SET_SYSTEM_AV_INFO is required. | |
836 | * | |
837 | * A frontend must guarantee that this environment call completes in | |
838 | * constant time. | |
839 | */ | |
840 | #define RETRO_ENVIRONMENT_GET_USERNAME 38 | |
841 | /* const char ** | |
842 | * Returns the specified username of the frontend, if specified by the user. | |
843 | * This username can be used as a nickname for a core that has online facilities | |
844 | * or any other mode where personalization of the user is desirable. | |
845 | * The returned value can be NULL. | |
846 | * If this environ callback is used by a core that requires a valid username, | |
847 | * a default username should be specified by the core. | |
848 | */ | |
849 | #define RETRO_ENVIRONMENT_GET_LANGUAGE 39 | |
850 | /* unsigned * -- | |
851 | * Returns the specified language of the frontend, if specified by the user. | |
852 | * It can be used by the core for localization purposes. | |
853 | */ | |
854 | ||
855 | #define RETRO_MEMDESC_CONST (1 << 0) /* The frontend will never change this memory area once retro_load_game has returned. */ | |
856 | #define RETRO_MEMDESC_BIGENDIAN (1 << 1) /* The memory area contains big endian data. Default is little endian. */ | |
857 | #define RETRO_MEMDESC_ALIGN_2 (1 << 16) /* All memory access in this area is aligned to their own size, or 2, whichever is smaller. */ | |
858 | #define RETRO_MEMDESC_ALIGN_4 (2 << 16) | |
859 | #define RETRO_MEMDESC_ALIGN_8 (3 << 16) | |
860 | #define RETRO_MEMDESC_MINSIZE_2 (1 << 24) /* All memory in this region is accessed at least 2 bytes at the time. */ | |
861 | #define RETRO_MEMDESC_MINSIZE_4 (2 << 24) | |
862 | #define RETRO_MEMDESC_MINSIZE_8 (3 << 24) | |
863 | struct retro_memory_descriptor | |
864 | { | |
865 | uint64_t flags; | |
866 | ||
867 | /* Pointer to the start of the relevant ROM or RAM chip. | |
868 | * It's strongly recommended to use 'offset' if possible, rather than | |
869 | * doing math on the pointer. | |
870 | * | |
871 | * If the same byte is mapped my multiple descriptors, their descriptors | |
872 | * must have the same pointer. | |
873 | * If 'start' does not point to the first byte in the pointer, put the | |
874 | * difference in 'offset' instead. | |
875 | * | |
876 | * May be NULL if there's nothing usable here (e.g. hardware registers and | |
877 | * open bus). No flags should be set if the pointer is NULL. | |
878 | * It's recommended to minimize the number of descriptors if possible, | |
879 | * but not mandatory. */ | |
880 | void *ptr; | |
881 | size_t offset; | |
882 | ||
883 | /* This is the location in the emulated address space | |
884 | * where the mapping starts. */ | |
885 | size_t start; | |
886 | ||
887 | /* Which bits must be same as in 'start' for this mapping to apply. | |
888 | * The first memory descriptor to claim a certain byte is the one | |
889 | * that applies. | |
890 | * A bit which is set in 'start' must also be set in this. | |
891 | * Can be zero, in which case each byte is assumed mapped exactly once. | |
892 | * In this case, 'len' must be a power of two. */ | |
893 | size_t select; | |
894 | ||
895 | /* If this is nonzero, the set bits are assumed not connected to the | |
896 | * memory chip's address pins. */ | |
897 | size_t disconnect; | |
898 | ||
899 | /* This one tells the size of the current memory area. | |
900 | * If, after start+disconnect are applied, the address is higher than | |
901 | * this, the highest bit of the address is cleared. | |
902 | * | |
903 | * If the address is still too high, the next highest bit is cleared. | |
904 | * Can be zero, in which case it's assumed to be infinite (as limited | |
905 | * by 'select' and 'disconnect'). */ | |
906 | size_t len; | |
907 | ||
908 | /* To go from emulated address to physical address, the following | |
909 | * order applies: | |
910 | * Subtract 'start', pick off 'disconnect', apply 'len', add 'offset'. | |
911 | * | |
912 | * The address space name must consist of only a-zA-Z0-9_-, | |
913 | * should be as short as feasible (maximum length is 8 plus the NUL), | |
914 | * and may not be any other address space plus one or more 0-9A-F | |
915 | * at the end. | |
916 | * However, multiple memory descriptors for the same address space is | |
917 | * allowed, and the address space name can be empty. NULL is treated | |
918 | * as empty. | |
919 | * | |
920 | * Address space names are case sensitive, but avoid lowercase if possible. | |
921 | * The same pointer may exist in multiple address spaces. | |
922 | * | |
923 | * Examples: | |
924 | * blank+blank - valid (multiple things may be mapped in the same namespace) | |
925 | * 'Sp'+'Sp' - valid (multiple things may be mapped in the same namespace) | |
926 | * 'A'+'B' - valid (neither is a prefix of each other) | |
927 | * 'S'+blank - valid ('S' is not in 0-9A-F) | |
928 | * 'a'+blank - valid ('a' is not in 0-9A-F) | |
929 | * 'a'+'A' - valid (neither is a prefix of each other) | |
930 | * 'AR'+blank - valid ('R' is not in 0-9A-F) | |
931 | * 'ARB'+blank - valid (the B can't be part of the address either, because | |
932 | * there is no namespace 'AR') | |
933 | * blank+'B' - not valid, because it's ambigous which address space B1234 | |
934 | * would refer to. | |
935 | * The length can't be used for that purpose; the frontend may want | |
936 | * to append arbitrary data to an address, without a separator. */ | |
937 | const char *addrspace; | |
938 | }; | |
939 | ||
940 | /* The frontend may use the largest value of 'start'+'select' in a | |
941 | * certain namespace to infer the size of the address space. | |
942 | * | |
943 | * If the address space is larger than that, a mapping with .ptr=NULL | |
944 | * should be at the end of the array, with .select set to all ones for | |
945 | * as long as the address space is big. | |
946 | * | |
947 | * Sample descriptors (minus .ptr, and RETRO_MEMFLAG_ on the flags): | |
948 | * SNES WRAM: | |
949 | * .start=0x7E0000, .len=0x20000 | |
950 | * (Note that this must be mapped before the ROM in most cases; some of the | |
951 | * ROM mappers | |
952 | * try to claim $7E0000, or at least $7E8000.) | |
953 | * SNES SPC700 RAM: | |
954 | * .addrspace="S", .len=0x10000 | |
955 | * SNES WRAM mirrors: | |
956 | * .flags=MIRROR, .start=0x000000, .select=0xC0E000, .len=0x2000 | |
957 | * .flags=MIRROR, .start=0x800000, .select=0xC0E000, .len=0x2000 | |
958 | * SNES WRAM mirrors, alternate equivalent descriptor: | |
959 | * .flags=MIRROR, .select=0x40E000, .disconnect=~0x1FFF | |
960 | * (Various similar constructions can be created by combining parts of | |
961 | * the above two.) | |
962 | * SNES LoROM (512KB, mirrored a couple of times): | |
963 | * .flags=CONST, .start=0x008000, .select=0x408000, .disconnect=0x8000, .len=512*1024 | |
964 | * .flags=CONST, .start=0x400000, .select=0x400000, .disconnect=0x8000, .len=512*1024 | |
965 | * SNES HiROM (4MB): | |
966 | * .flags=CONST, .start=0x400000, .select=0x400000, .len=4*1024*1024 | |
967 | * .flags=CONST, .offset=0x8000, .start=0x008000, .select=0x408000, .len=4*1024*1024 | |
968 | * SNES ExHiROM (8MB): | |
969 | * .flags=CONST, .offset=0, .start=0xC00000, .select=0xC00000, .len=4*1024*1024 | |
970 | * .flags=CONST, .offset=4*1024*1024, .start=0x400000, .select=0xC00000, .len=4*1024*1024 | |
971 | * .flags=CONST, .offset=0x8000, .start=0x808000, .select=0xC08000, .len=4*1024*1024 | |
972 | * .flags=CONST, .offset=4*1024*1024+0x8000, .start=0x008000, .select=0xC08000, .len=4*1024*1024 | |
973 | * Clarify the size of the address space: | |
974 | * .ptr=NULL, .select=0xFFFFFF | |
975 | * .len can be implied by .select in many of them, but was included for clarity. | |
976 | */ | |
977 | ||
978 | struct retro_memory_map | |
979 | { | |
980 | const struct retro_memory_descriptor *descriptors; | |
981 | unsigned num_descriptors; | |
982 | }; | |
983 | ||
984 | struct retro_controller_description | |
985 | { | |
986 | /* Human-readable description of the controller. Even if using a generic | |
987 | * input device type, this can be set to the particular device type the | |
988 | * core uses. */ | |
989 | const char *desc; | |
990 | ||
991 | /* Device type passed to retro_set_controller_port_device(). If the device | |
992 | * type is a sub-class of a generic input device type, use the | |
993 | * RETRO_DEVICE_SUBCLASS macro to create an ID. | |
994 | * | |
995 | * E.g. RETRO_DEVICE_SUBCLASS(RETRO_DEVICE_JOYPAD, 1). */ | |
996 | unsigned id; | |
997 | }; | |
998 | ||
999 | struct retro_controller_info | |
1000 | { | |
1001 | const struct retro_controller_description *types; | |
1002 | unsigned num_types; | |
1003 | }; | |
1004 | ||
1005 | struct retro_subsystem_memory_info | |
1006 | { | |
1007 | /* The extension associated with a memory type, e.g. "psram". */ | |
1008 | const char *extension; | |
1009 | ||
1010 | /* The memory type for retro_get_memory(). This should be at | |
1011 | * least 0x100 to avoid conflict with standardized | |
1012 | * libretro memory types. */ | |
1013 | unsigned type; | |
1014 | }; | |
1015 | ||
1016 | struct retro_subsystem_rom_info | |
1017 | { | |
1018 | /* Describes what the content is (SGB BIOS, GB ROM, etc). */ | |
1019 | const char *desc; | |
1020 | ||
1021 | /* Same definition as retro_get_system_info(). */ | |
1022 | const char *valid_extensions; | |
1023 | ||
1024 | /* Same definition as retro_get_system_info(). */ | |
1025 | bool need_fullpath; | |
1026 | ||
1027 | /* Same definition as retro_get_system_info(). */ | |
1028 | bool block_extract; | |
1029 | ||
1030 | /* This is set if the content is required to load a game. | |
1031 | * If this is set to false, a zeroed-out retro_game_info can be passed. */ | |
1032 | bool required; | |
1033 | ||
1034 | /* Content can have multiple associated persistent | |
1035 | * memory types (retro_get_memory()). */ | |
1036 | const struct retro_subsystem_memory_info *memory; | |
1037 | unsigned num_memory; | |
1038 | }; | |
1039 | ||
1040 | struct retro_subsystem_info | |
1041 | { | |
1042 | /* Human-readable string of the subsystem type, e.g. "Super GameBoy" */ | |
1043 | const char *desc; | |
1044 | ||
1045 | /* A computer friendly short string identifier for the subsystem type. | |
1046 | * This name must be [a-z]. | |
1047 | * E.g. if desc is "Super GameBoy", this can be "sgb". | |
1048 | * This identifier can be used for command-line interfaces, etc. | |
1049 | */ | |
1050 | const char *ident; | |
1051 | ||
1052 | /* Infos for each content file. The first entry is assumed to be the | |
1053 | * "most significant" content for frontend purposes. | |
1054 | * E.g. with Super GameBoy, the first content should be the GameBoy ROM, | |
1055 | * as it is the most "significant" content to a user. | |
1056 | * If a frontend creates new file paths based on the content used | |
1057 | * (e.g. savestates), it should use the path for the first ROM to do so. */ | |
1058 | const struct retro_subsystem_rom_info *roms; | |
1059 | ||
1060 | /* Number of content files associated with a subsystem. */ | |
1061 | unsigned num_roms; | |
1062 | ||
1063 | /* The type passed to retro_load_game_special(). */ | |
1064 | unsigned id; | |
1065 | }; | |
1066 | ||
1067 | typedef void (*retro_proc_address_t)(void); | |
1068 | ||
1069 | /* libretro API extension functions: | |
1070 | * (None here so far). | |
1071 | * | |
1072 | * Get a symbol from a libretro core. | |
1073 | * Cores should only return symbols which are actual | |
1074 | * extensions to the libretro API. | |
1075 | * | |
1076 | * Frontends should not use this to obtain symbols to standard | |
1077 | * libretro entry points (static linking or dlsym). | |
1078 | * | |
1079 | * The symbol name must be equal to the function name, | |
1080 | * e.g. if void retro_foo(void); exists, the symbol must be called "retro_foo". | |
1081 | * The returned function pointer must be cast to the corresponding type. | |
1082 | */ | |
1083 | typedef retro_proc_address_t (*retro_get_proc_address_t)(const char *sym); | |
1084 | ||
1085 | struct retro_get_proc_address_interface | |
1086 | { | |
1087 | retro_get_proc_address_t get_proc_address; | |
1088 | }; | |
c40ab498 | 1089 | |
1090 | enum retro_log_level | |
1091 | { | |
1092 | RETRO_LOG_DEBUG = 0, | |
1093 | RETRO_LOG_INFO, | |
1094 | RETRO_LOG_WARN, | |
1095 | RETRO_LOG_ERROR, | |
1096 | ||
1097 | RETRO_LOG_DUMMY = INT_MAX | |
1098 | }; | |
1099 | ||
7c830578 A |
1100 | /* Logging function. Takes log level argument as well. */ |
1101 | typedef void (*retro_log_printf_t)(enum retro_log_level level, | |
1102 | const char *fmt, ...); | |
c40ab498 | 1103 | |
1104 | struct retro_log_callback | |
1105 | { | |
1106 | retro_log_printf_t log; | |
1107 | }; | |
1108 | ||
7c830578 A |
1109 | /* Performance related functions */ |
1110 | ||
1111 | /* ID values for SIMD CPU features */ | |
c40ab498 | 1112 | #define RETRO_SIMD_SSE (1 << 0) |
1113 | #define RETRO_SIMD_SSE2 (1 << 1) | |
1114 | #define RETRO_SIMD_VMX (1 << 2) | |
1115 | #define RETRO_SIMD_VMX128 (1 << 3) | |
1116 | #define RETRO_SIMD_AVX (1 << 4) | |
1117 | #define RETRO_SIMD_NEON (1 << 5) | |
1118 | #define RETRO_SIMD_SSE3 (1 << 6) | |
1119 | #define RETRO_SIMD_SSSE3 (1 << 7) | |
7c830578 A |
1120 | #define RETRO_SIMD_MMX (1 << 8) |
1121 | #define RETRO_SIMD_MMXEXT (1 << 9) | |
1122 | #define RETRO_SIMD_SSE4 (1 << 10) | |
1123 | #define RETRO_SIMD_SSE42 (1 << 11) | |
1124 | #define RETRO_SIMD_AVX2 (1 << 12) | |
1125 | #define RETRO_SIMD_VFPU (1 << 13) | |
1126 | #define RETRO_SIMD_PS (1 << 14) | |
1127 | #define RETRO_SIMD_AES (1 << 15) | |
c40ab498 | 1128 | |
1129 | typedef uint64_t retro_perf_tick_t; | |
1130 | typedef int64_t retro_time_t; | |
1131 | ||
1132 | struct retro_perf_counter | |
1133 | { | |
1134 | const char *ident; | |
1135 | retro_perf_tick_t start; | |
1136 | retro_perf_tick_t total; | |
1137 | retro_perf_tick_t call_cnt; | |
1138 | ||
1139 | bool registered; | |
1140 | }; | |
1141 | ||
7c830578 A |
1142 | /* Returns current time in microseconds. |
1143 | * Tries to use the most accurate timer available. | |
1144 | */ | |
c40ab498 | 1145 | typedef retro_time_t (*retro_perf_get_time_usec_t)(void); |
7c830578 A |
1146 | |
1147 | /* A simple counter. Usually nanoseconds, but can also be CPU cycles. | |
1148 | * Can be used directly if desired (when creating a more sophisticated | |
1149 | * performance counter system). | |
1150 | * */ | |
c40ab498 | 1151 | typedef retro_perf_tick_t (*retro_perf_get_counter_t)(void); |
7c830578 A |
1152 | |
1153 | /* Returns a bit-mask of detected CPU features (RETRO_SIMD_*). */ | |
c40ab498 | 1154 | typedef uint64_t (*retro_get_cpu_features_t)(void); |
7c830578 A |
1155 | |
1156 | /* Asks frontend to log and/or display the state of performance counters. | |
1157 | * Performance counters can always be poked into manually as well. | |
1158 | */ | |
c40ab498 | 1159 | typedef void (*retro_perf_log_t)(void); |
7c830578 A |
1160 | |
1161 | /* Register a performance counter. | |
1162 | * ident field must be set with a discrete value and other values in | |
1163 | * retro_perf_counter must be 0. | |
1164 | * Registering can be called multiple times. To avoid calling to | |
1165 | * frontend redundantly, you can check registered field first. */ | |
c40ab498 | 1166 | typedef void (*retro_perf_register_t)(struct retro_perf_counter *counter); |
7c830578 A |
1167 | |
1168 | /* Starts a registered counter. */ | |
c40ab498 | 1169 | typedef void (*retro_perf_start_t)(struct retro_perf_counter *counter); |
7c830578 A |
1170 | |
1171 | /* Stops a registered counter. */ | |
c40ab498 | 1172 | typedef void (*retro_perf_stop_t)(struct retro_perf_counter *counter); |
1173 | ||
7c830578 A |
1174 | /* For convenience it can be useful to wrap register, start and stop in macros. |
1175 | * E.g.: | |
1176 | * #ifdef LOG_PERFORMANCE | |
1177 | * #define RETRO_PERFORMANCE_INIT(perf_cb, name) static struct retro_perf_counter name = {#name}; if (!name.registered) perf_cb.perf_register(&(name)) | |
1178 | * #define RETRO_PERFORMANCE_START(perf_cb, name) perf_cb.perf_start(&(name)) | |
1179 | * #define RETRO_PERFORMANCE_STOP(perf_cb, name) perf_cb.perf_stop(&(name)) | |
1180 | * #else | |
1181 | * ... Blank macros ... | |
1182 | * #endif | |
1183 | * | |
1184 | * These can then be used mid-functions around code snippets. | |
1185 | * | |
1186 | * extern struct retro_perf_callback perf_cb; * Somewhere in the core. | |
1187 | * | |
1188 | * void do_some_heavy_work(void) | |
1189 | * { | |
1190 | * RETRO_PERFORMANCE_INIT(cb, work_1; | |
1191 | * RETRO_PERFORMANCE_START(cb, work_1); | |
1192 | * heavy_work_1(); | |
1193 | * RETRO_PERFORMANCE_STOP(cb, work_1); | |
1194 | * | |
1195 | * RETRO_PERFORMANCE_INIT(cb, work_2); | |
1196 | * RETRO_PERFORMANCE_START(cb, work_2); | |
1197 | * heavy_work_2(); | |
1198 | * RETRO_PERFORMANCE_STOP(cb, work_2); | |
1199 | * } | |
1200 | * | |
1201 | * void retro_deinit(void) | |
1202 | * { | |
1203 | * perf_cb.perf_log(); * Log all perf counters here for example. | |
1204 | * } | |
1205 | */ | |
c40ab498 | 1206 | |
1207 | struct retro_perf_callback | |
1208 | { | |
1209 | retro_perf_get_time_usec_t get_time_usec; | |
1210 | retro_get_cpu_features_t get_cpu_features; | |
1211 | ||
1212 | retro_perf_get_counter_t get_perf_counter; | |
1213 | retro_perf_register_t perf_register; | |
1214 | retro_perf_start_t perf_start; | |
1215 | retro_perf_stop_t perf_stop; | |
1216 | retro_perf_log_t perf_log; | |
1217 | }; | |
1218 | ||
7c830578 A |
1219 | /* FIXME: Document the sensor API and work out behavior. |
1220 | * It will be marked as experimental until then. | |
1221 | */ | |
c40ab498 | 1222 | enum retro_sensor_action |
1223 | { | |
1224 | RETRO_SENSOR_ACCELEROMETER_ENABLE = 0, | |
1225 | RETRO_SENSOR_ACCELEROMETER_DISABLE, | |
1226 | ||
1227 | RETRO_SENSOR_DUMMY = INT_MAX | |
1228 | }; | |
1229 | ||
7c830578 A |
1230 | /* Id values for SENSOR types. */ |
1231 | #define RETRO_SENSOR_ACCELEROMETER_X 0 | |
1232 | #define RETRO_SENSOR_ACCELEROMETER_Y 1 | |
1233 | #define RETRO_SENSOR_ACCELEROMETER_Z 2 | |
1234 | ||
1235 | typedef bool (*retro_set_sensor_state_t)(unsigned port, | |
1236 | enum retro_sensor_action action, unsigned rate); | |
1237 | ||
1238 | typedef float (*retro_sensor_get_input_t)(unsigned port, unsigned id); | |
1239 | ||
c40ab498 | 1240 | struct retro_sensor_interface |
1241 | { | |
1242 | retro_set_sensor_state_t set_sensor_state; | |
7c830578 | 1243 | retro_sensor_get_input_t get_sensor_input; |
c40ab498 | 1244 | }; |
c40ab498 | 1245 | |
1246 | enum retro_camera_buffer | |
1247 | { | |
1248 | RETRO_CAMERA_BUFFER_OPENGL_TEXTURE = 0, | |
1249 | RETRO_CAMERA_BUFFER_RAW_FRAMEBUFFER, | |
1250 | ||
1251 | RETRO_CAMERA_BUFFER_DUMMY = INT_MAX | |
1252 | }; | |
1253 | ||
7c830578 | 1254 | /* Starts the camera driver. Can only be called in retro_run(). */ |
c40ab498 | 1255 | typedef bool (*retro_camera_start_t)(void); |
7c830578 A |
1256 | |
1257 | /* Stops the camera driver. Can only be called in retro_run(). */ | |
c40ab498 | 1258 | typedef void (*retro_camera_stop_t)(void); |
7c830578 A |
1259 | |
1260 | /* Callback which signals when the camera driver is initialized | |
1261 | * and/or deinitialized. | |
1262 | * retro_camera_start_t can be called in initialized callback. | |
1263 | */ | |
c40ab498 | 1264 | typedef void (*retro_camera_lifetime_status_t)(void); |
7c830578 A |
1265 | |
1266 | /* A callback for raw framebuffer data. buffer points to an XRGB8888 buffer. | |
1267 | * Width, height and pitch are similar to retro_video_refresh_t. | |
1268 | * First pixel is top-left origin. | |
1269 | */ | |
1270 | typedef void (*retro_camera_frame_raw_framebuffer_t)(const uint32_t *buffer, | |
1271 | unsigned width, unsigned height, size_t pitch); | |
1272 | ||
1273 | /* A callback for when OpenGL textures are used. | |
1274 | * | |
1275 | * texture_id is a texture owned by camera driver. | |
1276 | * Its state or content should be considered immutable, except for things like | |
1277 | * texture filtering and clamping. | |
1278 | * | |
1279 | * texture_target is the texture target for the GL texture. | |
1280 | * These can include e.g. GL_TEXTURE_2D, GL_TEXTURE_RECTANGLE, and possibly | |
1281 | * more depending on extensions. | |
1282 | * | |
1283 | * affine points to a packed 3x3 column-major matrix used to apply an affine | |
1284 | * transform to texture coordinates. (affine_matrix * vec3(coord_x, coord_y, 1.0)) | |
1285 | * After transform, normalized texture coord (0, 0) should be bottom-left | |
1286 | * and (1, 1) should be top-right (or (width, height) for RECTANGLE). | |
1287 | * | |
1288 | * GL-specific typedefs are avoided here to avoid relying on gl.h in | |
1289 | * the API definition. | |
1290 | */ | |
1291 | typedef void (*retro_camera_frame_opengl_texture_t)(unsigned texture_id, | |
1292 | unsigned texture_target, const float *affine); | |
1293 | ||
c40ab498 | 1294 | struct retro_camera_callback |
1295 | { | |
7c830578 A |
1296 | /* Set by libretro core. |
1297 | * Example bitmask: caps = (1 << RETRO_CAMERA_BUFFER_OPENGL_TEXTURE) | (1 << RETRO_CAMERA_BUFFER_RAW_FRAMEBUFFER). | |
1298 | */ | |
1299 | uint64_t caps; | |
c40ab498 | 1300 | |
7c830578 | 1301 | unsigned width; /* Desired resolution for camera. Is only used as a hint. */ |
c40ab498 | 1302 | unsigned height; |
7c830578 A |
1303 | retro_camera_start_t start; /* Set by frontend. */ |
1304 | retro_camera_stop_t stop; /* Set by frontend. */ | |
1305 | ||
1306 | /* Set by libretro core if raw framebuffer callbacks will be used. */ | |
1307 | retro_camera_frame_raw_framebuffer_t frame_raw_framebuffer; | |
1308 | /* Set by libretro core if OpenGL texture callbacks will be used. */ | |
1309 | retro_camera_frame_opengl_texture_t frame_opengl_texture; | |
1310 | ||
1311 | /* Set by libretro core. Called after camera driver is initialized and | |
1312 | * ready to be started. | |
1313 | * Can be NULL, in which this callback is not called. | |
1314 | */ | |
c40ab498 | 1315 | retro_camera_lifetime_status_t initialized; |
1316 | ||
7c830578 A |
1317 | /* Set by libretro core. Called right before camera driver is |
1318 | * deinitialized. | |
1319 | * Can be NULL, in which this callback is not called. | |
1320 | */ | |
c40ab498 | 1321 | retro_camera_lifetime_status_t deinitialized; |
1322 | }; | |
1323 | ||
7c830578 A |
1324 | /* Sets the interval of time and/or distance at which to update/poll |
1325 | * location-based data. | |
1326 | * | |
1327 | * To ensure compatibility with all location-based implementations, | |
1328 | * values for both interval_ms and interval_distance should be provided. | |
1329 | * | |
1330 | * interval_ms is the interval expressed in milliseconds. | |
1331 | * interval_distance is the distance interval expressed in meters. | |
1332 | */ | |
1333 | typedef void (*retro_location_set_interval_t)(unsigned interval_ms, | |
1334 | unsigned interval_distance); | |
1335 | ||
1336 | /* Start location services. The device will start listening for changes to the | |
1337 | * current location at regular intervals (which are defined with | |
1338 | * retro_location_set_interval_t). */ | |
1339 | typedef bool (*retro_location_start_t)(void); | |
1340 | ||
1341 | /* Stop location services. The device will stop listening for changes | |
1342 | * to the current location. */ | |
1343 | typedef void (*retro_location_stop_t)(void); | |
1344 | ||
1345 | /* Get the position of the current location. Will set parameters to | |
1346 | * 0 if no new location update has happened since the last time. */ | |
1347 | typedef bool (*retro_location_get_position_t)(double *lat, double *lon, | |
1348 | double *horiz_accuracy, double *vert_accuracy); | |
1349 | ||
1350 | /* Callback which signals when the location driver is initialized | |
1351 | * and/or deinitialized. | |
1352 | * retro_location_start_t can be called in initialized callback. | |
1353 | */ | |
1354 | typedef void (*retro_location_lifetime_status_t)(void); | |
1355 | ||
1356 | struct retro_location_callback | |
1357 | { | |
1358 | retro_location_start_t start; | |
1359 | retro_location_stop_t stop; | |
1360 | retro_location_get_position_t get_position; | |
1361 | retro_location_set_interval_t set_interval; | |
1362 | ||
1363 | retro_location_lifetime_status_t initialized; | |
1364 | retro_location_lifetime_status_t deinitialized; | |
1365 | }; | |
1366 | ||
c40ab498 | 1367 | enum retro_rumble_effect |
1368 | { | |
1369 | RETRO_RUMBLE_STRONG = 0, | |
1370 | RETRO_RUMBLE_WEAK = 1, | |
1371 | ||
1372 | RETRO_RUMBLE_DUMMY = INT_MAX | |
1373 | }; | |
1374 | ||
7c830578 A |
1375 | /* Sets rumble state for joypad plugged in port 'port'. |
1376 | * Rumble effects are controlled independently, | |
1377 | * and setting e.g. strong rumble does not override weak rumble. | |
1378 | * Strength has a range of [0, 0xffff]. | |
1379 | * | |
1380 | * Returns true if rumble state request was honored. | |
1381 | * Calling this before first retro_run() is likely to return false. */ | |
1382 | typedef bool (*retro_set_rumble_state_t)(unsigned port, | |
1383 | enum retro_rumble_effect effect, uint16_t strength); | |
1384 | ||
c40ab498 | 1385 | struct retro_rumble_interface |
1386 | { | |
1387 | retro_set_rumble_state_t set_rumble_state; | |
1388 | }; | |
1389 | ||
7c830578 | 1390 | /* Notifies libretro that audio data should be written. */ |
c40ab498 | 1391 | typedef void (*retro_audio_callback_t)(void); |
1392 | ||
7c830578 A |
1393 | /* True: Audio driver in frontend is active, and callback is |
1394 | * expected to be called regularily. | |
1395 | * False: Audio driver in frontend is paused or inactive. | |
1396 | * Audio callback will not be called until set_state has been | |
1397 | * called with true. | |
1398 | * Initial state is false (inactive). | |
1399 | */ | |
c40ab498 | 1400 | typedef void (*retro_audio_set_state_callback_t)(bool enabled); |
7c830578 | 1401 | |
c40ab498 | 1402 | struct retro_audio_callback |
1403 | { | |
1404 | retro_audio_callback_t callback; | |
1405 | retro_audio_set_state_callback_t set_state; | |
1406 | }; | |
1407 | ||
7c830578 A |
1408 | /* Notifies a libretro core of time spent since last invocation |
1409 | * of retro_run() in microseconds. | |
1410 | * | |
1411 | * It will be called right before retro_run() every frame. | |
1412 | * The frontend can tamper with timing to support cases like | |
1413 | * fast-forward, slow-motion and framestepping. | |
1414 | * | |
1415 | * In those scenarios the reference frame time value will be used. */ | |
c40ab498 | 1416 | typedef int64_t retro_usec_t; |
1417 | typedef void (*retro_frame_time_callback_t)(retro_usec_t usec); | |
1418 | struct retro_frame_time_callback | |
1419 | { | |
1420 | retro_frame_time_callback_t callback; | |
7c830578 A |
1421 | /* Represents the time of one frame. It is computed as |
1422 | * 1000000 / fps, but the implementation will resolve the | |
1423 | * rounding to ensure that framestepping, etc is exact. */ | |
1424 | retro_usec_t reference; | |
c40ab498 | 1425 | }; |
72f68e8c | 1426 | |
7c830578 A |
1427 | /* Pass this to retro_video_refresh_t if rendering to hardware. |
1428 | * Passing NULL to retro_video_refresh_t is still a frame dupe as normal. | |
1429 | * */ | |
72f68e8c | 1430 | #define RETRO_HW_FRAME_BUFFER_VALID ((void*)-1) |
1431 | ||
7c830578 A |
1432 | /* Invalidates the current HW context. |
1433 | * Any GL state is lost, and must not be deinitialized explicitly. | |
1434 | * If explicit deinitialization is desired by the libretro core, | |
1435 | * it should implement context_destroy callback. | |
1436 | * If called, all GPU resources must be reinitialized. | |
1437 | * Usually called when frontend reinits video driver. | |
1438 | * Also called first time video driver is initialized, | |
1439 | * allowing libretro core to initialize resources. | |
1440 | */ | |
72f68e8c | 1441 | typedef void (*retro_hw_context_reset_t)(void); |
7c830578 A |
1442 | |
1443 | /* Gets current framebuffer which is to be rendered to. | |
1444 | * Could change every frame potentially. | |
1445 | */ | |
72f68e8c | 1446 | typedef uintptr_t (*retro_hw_get_current_framebuffer_t)(void); |
1447 | ||
7c830578 | 1448 | /* Get a symbol from HW context. */ |
72f68e8c | 1449 | typedef retro_proc_address_t (*retro_hw_get_proc_address_t)(const char *sym); |
1450 | ||
1451 | enum retro_hw_context_type | |
1452 | { | |
7c830578 A |
1453 | RETRO_HW_CONTEXT_NONE = 0, |
1454 | /* OpenGL 2.x. Driver can choose to use latest compatibility context. */ | |
1455 | RETRO_HW_CONTEXT_OPENGL = 1, | |
1456 | /* OpenGL ES 2.0. */ | |
1457 | RETRO_HW_CONTEXT_OPENGLES2 = 2, | |
1458 | /* Modern desktop core GL context. Use version_major/ | |
1459 | * version_minor fields to set GL version. */ | |
1460 | RETRO_HW_CONTEXT_OPENGL_CORE = 3, | |
1461 | /* OpenGL ES 3.0 */ | |
1462 | RETRO_HW_CONTEXT_OPENGLES3 = 4, | |
1463 | /* OpenGL ES 3.1+. Set version_major/version_minor. For GLES2 and GLES3, | |
1464 | * use the corresponding enums directly. */ | |
1465 | RETRO_HW_CONTEXT_OPENGLES_VERSION = 5, | |
72f68e8c | 1466 | |
1467 | RETRO_HW_CONTEXT_DUMMY = INT_MAX | |
1468 | }; | |
23ea11bd | 1469 | |
72f68e8c | 1470 | struct retro_hw_render_callback |
1471 | { | |
7c830578 A |
1472 | /* Which API to use. Set by libretro core. */ |
1473 | enum retro_hw_context_type context_type; | |
1474 | ||
1475 | /* Called when a context has been created or when it has been reset. | |
1476 | * An OpenGL context is only valid after context_reset() has been called. | |
1477 | * | |
1478 | * When context_reset is called, OpenGL resources in the libretro | |
1479 | * implementation are guaranteed to be invalid. | |
1480 | * | |
1481 | * It is possible that context_reset is called multiple times during an | |
1482 | * application lifecycle. | |
1483 | * If context_reset is called without any notification (context_destroy), | |
1484 | * the OpenGL context was lost and resources should just be recreated | |
1485 | * without any attempt to "free" old resources. | |
1486 | */ | |
1487 | retro_hw_context_reset_t context_reset; | |
1488 | ||
1489 | /* Set by frontend. */ | |
1490 | retro_hw_get_current_framebuffer_t get_current_framebuffer; | |
1491 | ||
1492 | /* Set by frontend. */ | |
1493 | retro_hw_get_proc_address_t get_proc_address; | |
1494 | ||
1495 | /* Set if render buffers should have depth component attached. */ | |
1496 | bool depth; | |
1497 | ||
1498 | /* Set if stencil buffers should be attached. */ | |
1499 | bool stencil; | |
1500 | ||
1501 | /* If depth and stencil are true, a packed 24/8 buffer will be added. | |
1502 | * Only attaching stencil is invalid and will be ignored. */ | |
1503 | ||
1504 | /* Use conventional bottom-left origin convention. If false, | |
1505 | * standard libretro top-left origin semantics are used. */ | |
1506 | bool bottom_left_origin; | |
1507 | ||
1508 | /* Major version number for core GL context or GLES 3.1+. */ | |
1509 | unsigned version_major; | |
1510 | ||
1511 | /* Minor version number for core GL context or GLES 3.1+. */ | |
1512 | unsigned version_minor; | |
1513 | ||
1514 | /* If this is true, the frontend will go very far to avoid | |
1515 | * resetting context in scenarios like toggling fullscreen, etc. | |
1516 | */ | |
1517 | bool cache_context; | |
1518 | ||
1519 | /* The reset callback might still be called in extreme situations | |
1520 | * such as if the context is lost beyond recovery. | |
1521 | * | |
1522 | * For optimal stability, set this to false, and allow context to be | |
1523 | * reset at any time. | |
1524 | */ | |
1525 | ||
1526 | /* A callback to be called before the context is destroyed in a | |
1527 | * controlled way by the frontend. */ | |
1528 | retro_hw_context_reset_t context_destroy; | |
1529 | ||
1530 | /* OpenGL resources can be deinitialized cleanly at this step. | |
1531 | * context_destroy can be set to NULL, in which resources will | |
1532 | * just be destroyed without any notification. | |
1533 | * | |
1534 | * Even when context_destroy is non-NULL, it is possible that | |
1535 | * context_reset is called without any destroy notification. | |
1536 | * This happens if context is lost by external factors (such as | |
1537 | * notified by GL_ARB_robustness). | |
1538 | * | |
1539 | * In this case, the context is assumed to be already dead, | |
1540 | * and the libretro implementation must not try to free any OpenGL | |
1541 | * resources in the subsequent context_reset. | |
1542 | */ | |
1543 | ||
1544 | /* Creates a debug context. */ | |
1545 | bool debug_context; | |
72f68e8c | 1546 | }; |
c19aba43 | 1547 | |
7c830578 A |
1548 | /* Callback type passed in RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK. |
1549 | * Called by the frontend in response to keyboard events. | |
1550 | * down is set if the key is being pressed, or false if it is being released. | |
1551 | * keycode is the RETROK value of the char. | |
1552 | * character is the text character of the pressed key. (UTF-32). | |
1553 | * key_modifiers is a set of RETROKMOD values or'ed together. | |
1554 | * | |
1555 | * The pressed/keycode state can be indepedent of the character. | |
1556 | * It is also possible that multiple characters are generated from a | |
1557 | * single keypress. | |
1558 | * Keycode events should be treated separately from character events. | |
1559 | * However, when possible, the frontend should try to synchronize these. | |
1560 | * If only a character is posted, keycode should be RETROK_UNKNOWN. | |
1561 | * | |
1562 | * Similarily if only a keycode event is generated with no corresponding | |
1563 | * character, character should be 0. | |
1564 | */ | |
1565 | typedef void (*retro_keyboard_event_t)(bool down, unsigned keycode, | |
1566 | uint32_t character, uint16_t key_modifiers); | |
23ea11bd | 1567 | |
1568 | struct retro_keyboard_callback | |
1569 | { | |
e268a47e | 1570 | retro_keyboard_event_t callback; |
23ea11bd | 1571 | }; |
1572 | ||
7c830578 A |
1573 | /* Callbacks for RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE. |
1574 | * Should be set for implementations which can swap out multiple disk | |
1575 | * images in runtime. | |
1576 | * | |
1577 | * If the implementation can do this automatically, it should strive to do so. | |
1578 | * However, there are cases where the user must manually do so. | |
1579 | * | |
1580 | * Overview: To swap a disk image, eject the disk image with | |
1581 | * set_eject_state(true). | |
1582 | * Set the disk index with set_image_index(index). Insert the disk again | |
1583 | * with set_eject_state(false). | |
1584 | */ | |
23ea11bd | 1585 | |
7c830578 A |
1586 | /* If ejected is true, "ejects" the virtual disk tray. |
1587 | * When ejected, the disk image index can be set. | |
1588 | */ | |
23ea11bd | 1589 | typedef bool (*retro_set_eject_state_t)(bool ejected); |
7c830578 A |
1590 | |
1591 | /* Gets current eject state. The initial state is 'not ejected'. */ | |
23ea11bd | 1592 | typedef bool (*retro_get_eject_state_t)(void); |
7c830578 A |
1593 | |
1594 | /* Gets current disk index. First disk is index 0. | |
1595 | * If return value is >= get_num_images(), no disk is currently inserted. | |
1596 | */ | |
23ea11bd | 1597 | typedef unsigned (*retro_get_image_index_t)(void); |
7c830578 A |
1598 | |
1599 | /* Sets image index. Can only be called when disk is ejected. | |
1600 | * The implementation supports setting "no disk" by using an | |
1601 | * index >= get_num_images(). | |
1602 | */ | |
23ea11bd | 1603 | typedef bool (*retro_set_image_index_t)(unsigned index); |
7c830578 A |
1604 | |
1605 | /* Gets total number of images which are available to use. */ | |
23ea11bd | 1606 | typedef unsigned (*retro_get_num_images_t)(void); |
7c830578 | 1607 | |
23ea11bd | 1608 | struct retro_game_info; |
7c830578 A |
1609 | |
1610 | /* Replaces the disk image associated with index. | |
1611 | * Arguments to pass in info have same requirements as retro_load_game(). | |
1612 | * Virtual disk tray must be ejected when calling this. | |
1613 | * | |
1614 | * Replacing a disk image with info = NULL will remove the disk image | |
1615 | * from the internal list. | |
1616 | * As a result, calls to get_image_index() can change. | |
1617 | * | |
1618 | * E.g. replace_image_index(1, NULL), and previous get_image_index() | |
1619 | * returned 4 before. | |
1620 | * Index 1 will be removed, and the new index is 3. | |
1621 | */ | |
1622 | typedef bool (*retro_replace_image_index_t)(unsigned index, | |
1623 | const struct retro_game_info *info); | |
1624 | ||
1625 | /* Adds a new valid index (get_num_images()) to the internal disk list. | |
1626 | * This will increment subsequent return values from get_num_images() by 1. | |
1627 | * This image index cannot be used until a disk image has been set | |
1628 | * with replace_image_index. */ | |
23ea11bd | 1629 | typedef bool (*retro_add_image_index_t)(void); |
1630 | ||
1631 | struct retro_disk_control_callback | |
1632 | { | |
1633 | retro_set_eject_state_t set_eject_state; | |
1634 | retro_get_eject_state_t get_eject_state; | |
1635 | ||
1636 | retro_get_image_index_t get_image_index; | |
1637 | retro_set_image_index_t set_image_index; | |
1638 | retro_get_num_images_t get_num_images; | |
1639 | ||
1640 | retro_replace_image_index_t replace_image_index; | |
1641 | retro_add_image_index_t add_image_index; | |
1642 | }; | |
38c2028e | 1643 | |
1644 | enum retro_pixel_format | |
1645 | { | |
7c830578 A |
1646 | /* 0RGB1555, native endian. |
1647 | * 0 bit must be set to 0. | |
1648 | * This pixel format is default for compatibility concerns only. | |
1649 | * If a 15/16-bit pixel format is desired, consider using RGB565. */ | |
c19aba43 TK |
1650 | RETRO_PIXEL_FORMAT_0RGB1555 = 0, |
1651 | ||
7c830578 A |
1652 | /* XRGB8888, native endian. |
1653 | * X bits are ignored. */ | |
c19aba43 TK |
1654 | RETRO_PIXEL_FORMAT_XRGB8888 = 1, |
1655 | ||
7c830578 A |
1656 | /* RGB565, native endian. |
1657 | * This pixel format is the recommended format to use if a 15/16-bit | |
1658 | * format is desired as it is the pixel format that is typically | |
1659 | * available on a wide range of low-power devices. | |
1660 | * | |
1661 | * It is also natively supported in APIs like OpenGL ES. */ | |
c19aba43 TK |
1662 | RETRO_PIXEL_FORMAT_RGB565 = 2, |
1663 | ||
7c830578 | 1664 | /* Ensure sizeof() == sizeof(int). */ |
c19aba43 | 1665 | RETRO_PIXEL_FORMAT_UNKNOWN = INT_MAX |
38c2028e | 1666 | }; |
1667 | ||
1668 | struct retro_message | |
1669 | { | |
7c830578 A |
1670 | const char *msg; /* Message to be displayed. */ |
1671 | unsigned frames; /* Duration in frames of message. */ | |
38c2028e | 1672 | }; |
1673 | ||
7c830578 A |
1674 | /* Describes how the libretro implementation maps a libretro input bind |
1675 | * to its internal input system through a human readable string. | |
1676 | * This string can be used to better let a user configure input. */ | |
c19aba43 TK |
1677 | struct retro_input_descriptor |
1678 | { | |
7c830578 | 1679 | /* Associates given parameters with a description. */ |
c19aba43 TK |
1680 | unsigned port; |
1681 | unsigned device; | |
1682 | unsigned index; | |
1683 | unsigned id; | |
1684 | ||
7c830578 A |
1685 | /* Human readable description for parameters. |
1686 | * The pointer must remain valid until | |
1687 | * retro_unload_game() is called. */ | |
1688 | const char *description; | |
c19aba43 TK |
1689 | }; |
1690 | ||
38c2028e | 1691 | struct retro_system_info |
1692 | { | |
7c830578 A |
1693 | /* All pointers are owned by libretro implementation, and pointers must |
1694 | * remain valid until retro_deinit() is called. */ | |
1695 | ||
1696 | const char *library_name; /* Descriptive name of library. Should not | |
1697 | * contain any version numbers, etc. */ | |
1698 | const char *library_version; /* Descriptive version of core. */ | |
1699 | ||
1700 | const char *valid_extensions; /* A string listing probably content | |
1701 | * extensions the core will be able to | |
1702 | * load, separated with pipe. | |
1703 | * I.e. "bin|rom|iso". | |
1704 | * Typically used for a GUI to filter | |
1705 | * out extensions. */ | |
1706 | ||
1707 | /* If true, retro_load_game() is guaranteed to provide a valid pathname | |
1708 | * in retro_game_info::path. | |
1709 | * ::data and ::size are both invalid. | |
1710 | * | |
1711 | * If false, ::data and ::size are guaranteed to be valid, but ::path | |
1712 | * might not be valid. | |
1713 | * | |
1714 | * This is typically set to true for libretro implementations that must | |
1715 | * load from file. | |
1716 | * Implementations should strive for setting this to false, as it allows | |
1717 | * the frontend to perform patching, etc. */ | |
1718 | bool need_fullpath; | |
1719 | ||
1720 | /* If true, the frontend is not allowed to extract any archives before | |
1721 | * loading the real content. | |
1722 | * Necessary for certain libretro implementations that load games | |
1723 | * from zipped archives. */ | |
1724 | bool block_extract; | |
38c2028e | 1725 | }; |
1726 | ||
1727 | struct retro_game_geometry | |
1728 | { | |
7c830578 A |
1729 | unsigned base_width; /* Nominal video width of game. */ |
1730 | unsigned base_height; /* Nominal video height of game. */ | |
1731 | unsigned max_width; /* Maximum possible width of game. */ | |
1732 | unsigned max_height; /* Maximum possible height of game. */ | |
1733 | ||
1734 | float aspect_ratio; /* Nominal aspect ratio of game. If | |
1735 | * aspect_ratio is <= 0.0, an aspect ratio | |
1736 | * of base_width / base_height is assumed. | |
1737 | * A frontend could override this setting, | |
1738 | * if desired. */ | |
38c2028e | 1739 | }; |
1740 | ||
1741 | struct retro_system_timing | |
1742 | { | |
7c830578 A |
1743 | double fps; /* FPS of video content. */ |
1744 | double sample_rate; /* Sampling rate of audio. */ | |
38c2028e | 1745 | }; |
1746 | ||
1747 | struct retro_system_av_info | |
1748 | { | |
1749 | struct retro_game_geometry geometry; | |
1750 | struct retro_system_timing timing; | |
1751 | }; | |
1752 | ||
1753 | struct retro_variable | |
1754 | { | |
7c830578 A |
1755 | /* Variable to query in RETRO_ENVIRONMENT_GET_VARIABLE. |
1756 | * If NULL, obtains the complete environment string if more | |
1757 | * complex parsing is necessary. | |
1758 | * The environment string is formatted as key-value pairs | |
1759 | * delimited by semicolons as so: | |
1760 | * "key1=value1;key2=value2;..." | |
1761 | */ | |
1762 | const char *key; | |
1763 | ||
1764 | /* Value to be obtained. If key does not exist, it is set to NULL. */ | |
1765 | const char *value; | |
38c2028e | 1766 | }; |
1767 | ||
1768 | struct retro_game_info | |
1769 | { | |
7c830578 A |
1770 | const char *path; /* Path to game, UTF-8 encoded. |
1771 | * Usually used as a reference. | |
1772 | * May be NULL if rom was loaded from stdin | |
1773 | * or similar. | |
1774 | * retro_system_info::need_fullpath guaranteed | |
1775 | * that this path is valid. */ | |
1776 | const void *data; /* Memory buffer of loaded game. Will be NULL | |
1777 | * if need_fullpath was set. */ | |
1778 | size_t size; /* Size of memory buffer. */ | |
1779 | const char *meta; /* String of implementation specific meta-data. */ | |
38c2028e | 1780 | }; |
1781 | ||
7c830578 A |
1782 | /* Callbacks */ |
1783 | ||
1784 | /* Environment callback. Gives implementations a way of performing | |
1785 | * uncommon tasks. Extensible. */ | |
38c2028e | 1786 | typedef bool (*retro_environment_t)(unsigned cmd, void *data); |
1787 | ||
7c830578 A |
1788 | /* Render a frame. Pixel format is 15-bit 0RGB1555 native endian |
1789 | * unless changed (see RETRO_ENVIRONMENT_SET_PIXEL_FORMAT). | |
1790 | * | |
1791 | * Width and height specify dimensions of buffer. | |
1792 | * Pitch specifices length in bytes between two lines in buffer. | |
1793 | * | |
1794 | * For performance reasons, it is highly recommended to have a frame | |
1795 | * that is packed in memory, i.e. pitch == width * byte_per_pixel. | |
1796 | * Certain graphic APIs, such as OpenGL ES, do not like textures | |
1797 | * that are not packed in memory. | |
1798 | */ | |
1799 | typedef void (*retro_video_refresh_t)(const void *data, unsigned width, | |
1800 | unsigned height, size_t pitch); | |
38c2028e | 1801 | |
7c830578 A |
1802 | /* Renders a single audio frame. Should only be used if implementation |
1803 | * generates a single sample at a time. | |
1804 | * Format is signed 16-bit native endian. | |
1805 | */ | |
38c2028e | 1806 | typedef void (*retro_audio_sample_t)(int16_t left, int16_t right); |
38c2028e | 1807 | |
7c830578 A |
1808 | /* Renders multiple audio frames in one go. |
1809 | * | |
1810 | * One frame is defined as a sample of left and right channels, interleaved. | |
1811 | * I.e. int16_t buf[4] = { l, r, l, r }; would be 2 frames. | |
1812 | * Only one of the audio callbacks must ever be used. | |
1813 | */ | |
1814 | typedef size_t (*retro_audio_sample_batch_t)(const int16_t *data, | |
1815 | size_t frames); | |
1816 | ||
1817 | /* Polls input. */ | |
38c2028e | 1818 | typedef void (*retro_input_poll_t)(void); |
38c2028e | 1819 | |
7c830578 A |
1820 | /* Queries for input for player 'port'. device will be masked with |
1821 | * RETRO_DEVICE_MASK. | |
1822 | * | |
1823 | * Specialization of devices such as RETRO_DEVICE_JOYPAD_MULTITAP that | |
1824 | * have been set with retro_set_controller_port_device() | |
1825 | * will still use the higher level RETRO_DEVICE_JOYPAD to request input. | |
1826 | */ | |
1827 | typedef int16_t (*retro_input_state_t)(unsigned port, unsigned device, | |
1828 | unsigned index, unsigned id); | |
1829 | ||
1830 | /* Sets callbacks. retro_set_environment() is guaranteed to be called | |
1831 | * before retro_init(). | |
1832 | * | |
1833 | * The rest of the set_* functions are guaranteed to have been called | |
1834 | * before the first call to retro_run() is made. */ | |
38c2028e | 1835 | void retro_set_environment(retro_environment_t); |
1836 | void retro_set_video_refresh(retro_video_refresh_t); | |
1837 | void retro_set_audio_sample(retro_audio_sample_t); | |
1838 | void retro_set_audio_sample_batch(retro_audio_sample_batch_t); | |
1839 | void retro_set_input_poll(retro_input_poll_t); | |
1840 | void retro_set_input_state(retro_input_state_t); | |
1841 | ||
7c830578 | 1842 | /* Library global initialization/deinitialization. */ |
38c2028e | 1843 | void retro_init(void); |
1844 | void retro_deinit(void); | |
1845 | ||
7c830578 A |
1846 | /* Must return RETRO_API_VERSION. Used to validate ABI compatibility |
1847 | * when the API is revised. */ | |
38c2028e | 1848 | unsigned retro_api_version(void); |
1849 | ||
7c830578 A |
1850 | /* Gets statically known system info. Pointers provided in *info |
1851 | * must be statically allocated. | |
1852 | * Can be called at any time, even before retro_init(). */ | |
38c2028e | 1853 | void retro_get_system_info(struct retro_system_info *info); |
1854 | ||
7c830578 A |
1855 | /* Gets information about system audio/video timings and geometry. |
1856 | * Can be called only after retro_load_game() has successfully completed. | |
1857 | * NOTE: The implementation of this function might not initialize every | |
1858 | * variable if needed. | |
1859 | * E.g. geom.aspect_ratio might not be initialized if core doesn't | |
1860 | * desire a particular aspect ratio. */ | |
38c2028e | 1861 | void retro_get_system_av_info(struct retro_system_av_info *info); |
1862 | ||
7c830578 A |
1863 | /* Sets device to be used for player 'port'. |
1864 | * By default, RETRO_DEVICE_JOYPAD is assumed to be plugged into all | |
1865 | * available ports. | |
1866 | * Setting a particular device type is not a guarantee that libretro cores | |
1867 | * will only poll input based on that particular device type. It is only a | |
1868 | * hint to the libretro core when a core cannot automatically detect the | |
1869 | * appropriate input device type on its own. It is also relevant when a | |
1870 | * core can change its behavior depending on device type. */ | |
38c2028e | 1871 | void retro_set_controller_port_device(unsigned port, unsigned device); |
1872 | ||
7c830578 | 1873 | /* Resets the current game. */ |
38c2028e | 1874 | void retro_reset(void); |
1875 | ||
7c830578 A |
1876 | /* Runs the game for one video frame. |
1877 | * During retro_run(), input_poll callback must be called at least once. | |
1878 | * | |
1879 | * If a frame is not rendered for reasons where a game "dropped" a frame, | |
1880 | * this still counts as a frame, and retro_run() should explicitly dupe | |
1881 | * a frame if GET_CAN_DUPE returns true. | |
1882 | * In this case, the video callback can take a NULL argument for data. | |
1883 | */ | |
38c2028e | 1884 | void retro_run(void); |
1885 | ||
7c830578 A |
1886 | /* Returns the amount of data the implementation requires to serialize |
1887 | * internal state (save states). | |
1888 | * Between calls to retro_load_game() and retro_unload_game(), the | |
1889 | * returned size is never allowed to be larger than a previous returned | |
1890 | * value, to ensure that the frontend can allocate a save state buffer once. | |
1891 | */ | |
38c2028e | 1892 | size_t retro_serialize_size(void); |
1893 | ||
7c830578 A |
1894 | /* Serializes internal state. If failed, or size is lower than |
1895 | * retro_serialize_size(), it should return false, true otherwise. */ | |
38c2028e | 1896 | bool retro_serialize(void *data, size_t size); |
1897 | bool retro_unserialize(const void *data, size_t size); | |
1898 | ||
1899 | void retro_cheat_reset(void); | |
1900 | void retro_cheat_set(unsigned index, bool enabled, const char *code); | |
1901 | ||
7c830578 | 1902 | /* Loads a game. */ |
38c2028e | 1903 | bool retro_load_game(const struct retro_game_info *game); |
1904 | ||
7c830578 A |
1905 | /* Loads a "special" kind of game. Should not be used, |
1906 | * except in extreme cases. */ | |
38c2028e | 1907 | bool retro_load_game_special( |
1908 | unsigned game_type, | |
1909 | const struct retro_game_info *info, size_t num_info | |
1910 | ); | |
1911 | ||
7c830578 | 1912 | /* Unloads a currently loaded game. */ |
38c2028e | 1913 | void retro_unload_game(void); |
1914 | ||
7c830578 | 1915 | /* Gets region of game. */ |
38c2028e | 1916 | unsigned retro_get_region(void); |
1917 | ||
7c830578 | 1918 | /* Gets region of memory. */ |
38c2028e | 1919 | void *retro_get_memory_data(unsigned id); |
1920 | size_t retro_get_memory_size(unsigned id); | |
1921 | ||
1922 | #ifdef __cplusplus | |
1923 | } | |
1924 | #endif | |
1925 | ||
1926 | #endif |