7612bf90 |
1 | /* Copyright (C) 2010-2014 The RetroArch team |
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 | |
23 | #ifndef LIBRETRO_H__ |
24 | #define LIBRETRO_H__ |
25 | |
26 | #include <stdint.h> |
27 | #include <stddef.h> |
28 | #include <limits.h> |
29 | |
30 | #ifdef __cplusplus |
31 | extern "C" { |
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. */ |
38 | #define bool unsigned char |
39 | #define true 1 |
40 | #define false 0 |
41 | #else |
42 | #include <stdbool.h> |
43 | #endif |
44 | #endif |
45 | |
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 | */ |
50 | #define RETRO_API_VERSION 1 |
51 | |
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. */ |
71 | #define RETRO_DEVICE_NONE 0 |
72 | |
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. */ |
76 | #define RETRO_DEVICE_JOYPAD 1 |
77 | |
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 | */ |
85 | #define RETRO_DEVICE_MOUSE 2 |
86 | |
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 | */ |
93 | #define RETRO_DEVICE_KEYBOARD 3 |
94 | |
95 | /* Lightgun X/Y coordinates are reported relatively to last poll, |
96 | * similar to mouse. */ |
97 | #define RETRO_DEVICE_LIGHTGUN 4 |
98 | |
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 | */ |
106 | #define RETRO_DEVICE_ANALOG 5 |
107 | |
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. */ |
138 | #define RETRO_DEVICE_POINTER 6 |
139 | |
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. */ |
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 | |
161 | /* Index / Id values for ANALOG device. */ |
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 | |
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 |
175 | |
176 | /* Id values for LIGHTGUN types. */ |
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 | |
185 | /* Id values for POINTER. */ |
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 | |
190 | /* Returned from retro_get_region(). */ |
191 | #define RETRO_REGION_NTSC 0 |
192 | #define RETRO_REGION_PAL 1 |
193 | |
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 | */ |
219 | #define RETRO_MEMORY_MASK 0xff |
220 | |
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. */ |
226 | #define RETRO_MEMORY_SAVE_RAM 0 |
227 | |
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 | */ |
231 | #define RETRO_MEMORY_RTC 1 |
232 | |
233 | /* System ram lets a frontend peek into a game systems main RAM. */ |
234 | #define RETRO_MEMORY_SYSTEM_RAM 2 |
235 | |
236 | /* Video ram lets a frontend peek into a game systems video RAM (VRAM). */ |
237 | #define RETRO_MEMORY_VIDEO_RAM 3 |
238 | |
239 | /* Keysyms used for ID in input state callback when polling RETRO_KEYBOARD. */ |
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 | |
385 | RETROK_LAST, |
386 | |
387 | RETROK_DUMMY = INT_MAX /* Ensure sizeof(enum) == sizeof(int) */ |
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 | |
403 | RETROKMOD_DUMMY = INT_MAX /* Ensure sizeof(enum) == sizeof(int) */ |
404 | }; |
405 | |
406 | /* If set, this call is not part of the public libretro API yet. It can |
407 | * change or be removed at any time. */ |
408 | #define RETRO_ENVIRONMENT_EXPERIMENTAL 0x10000 |
409 | /* Environment callback to be used internally in frontend. */ |
410 | #define RETRO_ENVIRONMENT_PRIVATE 0x20000 |
411 | |
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 | */ |
444 | #define RETRO_ENVIRONMENT_SET_PERFORMANCE_LEVEL 8 |
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 | */ |
461 | #define RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY 9 |
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 | */ |
475 | #define RETRO_ENVIRONMENT_SET_PIXEL_FORMAT 10 |
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 | */ |
486 | #define RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS 11 |
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 | */ |
495 | #define RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK 12 |
496 | /* const struct retro_keyboard_callback * -- |
497 | * Sets a callback function used to notify core about keyboard events. |
498 | */ |
499 | #define RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE 13 |
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 | */ |
506 | #define RETRO_ENVIRONMENT_SET_HW_RENDER 14 |
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 | */ |
518 | #define RETRO_ENVIRONMENT_GET_VARIABLE 15 |
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 | */ |
526 | #define RETRO_ENVIRONMENT_SET_VARIABLES 16 |
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 | */ |
561 | #define RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE 17 |
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 | */ |
567 | #define RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME 18 |
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 | */ |
574 | #define RETRO_ENVIRONMENT_GET_LIBRETRO_PATH 19 |
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. */ |
588 | #define RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK 22 |
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 | */ |
614 | #define RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK 21 |
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 | */ |
623 | #define RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE 23 |
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 | */ |
630 | #define RETRO_ENVIRONMENT_GET_INPUT_DEVICE_CAPABILITIES 24 |
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 | */ |
639 | #define RETRO_ENVIRONMENT_GET_SENSOR_INTERFACE (25 | RETRO_ENVIRONMENT_EXPERIMENTAL) |
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 | */ |
648 | #define RETRO_ENVIRONMENT_GET_CAMERA_INTERFACE (26 | RETRO_ENVIRONMENT_EXPERIMENTAL) |
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 | */ |
673 | #define RETRO_ENVIRONMENT_GET_LOG_INTERFACE 27 |
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 | */ |
683 | #define RETRO_ENVIRONMENT_GET_PERF_INTERFACE 28 |
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 | }; |
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 | |
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, ...); |
1103 | |
1104 | struct retro_log_callback |
1105 | { |
1106 | retro_log_printf_t log; |
1107 | }; |
1108 | |
1109 | /* Performance related functions */ |
1110 | |
1111 | /* ID values for SIMD CPU features */ |
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) |
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) |
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 | |
1142 | /* Returns current time in microseconds. |
1143 | * Tries to use the most accurate timer available. |
1144 | */ |
1145 | typedef retro_time_t (*retro_perf_get_time_usec_t)(void); |
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 | * */ |
1151 | typedef retro_perf_tick_t (*retro_perf_get_counter_t)(void); |
1152 | |
1153 | /* Returns a bit-mask of detected CPU features (RETRO_SIMD_*). */ |
1154 | typedef uint64_t (*retro_get_cpu_features_t)(void); |
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 | */ |
1159 | typedef void (*retro_perf_log_t)(void); |
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. */ |
1166 | typedef void (*retro_perf_register_t)(struct retro_perf_counter *counter); |
1167 | |
1168 | /* Starts a registered counter. */ |
1169 | typedef void (*retro_perf_start_t)(struct retro_perf_counter *counter); |
1170 | |
1171 | /* Stops a registered counter. */ |
1172 | typedef void (*retro_perf_stop_t)(struct retro_perf_counter *counter); |
1173 | |
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 | */ |
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 | |
1219 | /* FIXME: Document the sensor API and work out behavior. |
1220 | * It will be marked as experimental until then. |
1221 | */ |
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 | |
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 | |
1240 | struct retro_sensor_interface |
1241 | { |
1242 | retro_set_sensor_state_t set_sensor_state; |
1243 | retro_sensor_get_input_t get_sensor_input; |
1244 | }; |
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 | |
1254 | /* Starts the camera driver. Can only be called in retro_run(). */ |
1255 | typedef bool (*retro_camera_start_t)(void); |
1256 | |
1257 | /* Stops the camera driver. Can only be called in retro_run(). */ |
1258 | typedef void (*retro_camera_stop_t)(void); |
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 | */ |
1264 | typedef void (*retro_camera_lifetime_status_t)(void); |
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 | |
1294 | struct retro_camera_callback |
1295 | { |
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; |
1300 | |
1301 | unsigned width; /* Desired resolution for camera. Is only used as a hint. */ |
1302 | unsigned height; |
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 | */ |
1315 | retro_camera_lifetime_status_t initialized; |
1316 | |
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 | */ |
1321 | retro_camera_lifetime_status_t deinitialized; |
1322 | }; |
1323 | |
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 | |
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 | |
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 | |
1385 | struct retro_rumble_interface |
1386 | { |
1387 | retro_set_rumble_state_t set_rumble_state; |
1388 | }; |
1389 | |
1390 | /* Notifies libretro that audio data should be written. */ |
1391 | typedef void (*retro_audio_callback_t)(void); |
1392 | |
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 | */ |
1400 | typedef void (*retro_audio_set_state_callback_t)(bool enabled); |
1401 | |
1402 | struct retro_audio_callback |
1403 | { |
1404 | retro_audio_callback_t callback; |
1405 | retro_audio_set_state_callback_t set_state; |
1406 | }; |
1407 | |
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. */ |
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; |
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; |
1425 | }; |
1426 | |
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 | * */ |
1430 | #define RETRO_HW_FRAME_BUFFER_VALID ((void*)-1) |
1431 | |
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 | */ |
1441 | typedef void (*retro_hw_context_reset_t)(void); |
1442 | |
1443 | /* Gets current framebuffer which is to be rendered to. |
1444 | * Could change every frame potentially. |
1445 | */ |
1446 | typedef uintptr_t (*retro_hw_get_current_framebuffer_t)(void); |
1447 | |
1448 | /* Get a symbol from HW context. */ |
1449 | typedef retro_proc_address_t (*retro_hw_get_proc_address_t)(const char *sym); |
1450 | |
1451 | enum retro_hw_context_type |
1452 | { |
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, |
1466 | |
1467 | RETRO_HW_CONTEXT_DUMMY = INT_MAX |
1468 | }; |
1469 | |
1470 | struct retro_hw_render_callback |
1471 | { |
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; |
1546 | }; |
1547 | |
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); |
1567 | |
1568 | struct retro_keyboard_callback |
1569 | { |
1570 | retro_keyboard_event_t callback; |
1571 | }; |
1572 | |
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 | */ |
1585 | |
1586 | /* If ejected is true, "ejects" the virtual disk tray. |
1587 | * When ejected, the disk image index can be set. |
1588 | */ |
1589 | typedef bool (*retro_set_eject_state_t)(bool ejected); |
1590 | |
1591 | /* Gets current eject state. The initial state is 'not ejected'. */ |
1592 | typedef bool (*retro_get_eject_state_t)(void); |
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 | */ |
1597 | typedef unsigned (*retro_get_image_index_t)(void); |
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 | */ |
1603 | typedef bool (*retro_set_image_index_t)(unsigned index); |
1604 | |
1605 | /* Gets total number of images which are available to use. */ |
1606 | typedef unsigned (*retro_get_num_images_t)(void); |
1607 | |
1608 | struct retro_game_info; |
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. */ |
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 | }; |
1643 | |
1644 | enum retro_pixel_format |
1645 | { |
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. */ |
1650 | RETRO_PIXEL_FORMAT_0RGB1555 = 0, |
1651 | |
1652 | /* XRGB8888, native endian. |
1653 | * X bits are ignored. */ |
1654 | RETRO_PIXEL_FORMAT_XRGB8888 = 1, |
1655 | |
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. */ |
1662 | RETRO_PIXEL_FORMAT_RGB565 = 2, |
1663 | |
1664 | /* Ensure sizeof() == sizeof(int). */ |
1665 | RETRO_PIXEL_FORMAT_UNKNOWN = INT_MAX |
1666 | }; |
1667 | |
1668 | struct retro_message |
1669 | { |
1670 | const char *msg; /* Message to be displayed. */ |
1671 | unsigned frames; /* Duration in frames of message. */ |
1672 | }; |
1673 | |
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. */ |
1677 | struct retro_input_descriptor |
1678 | { |
1679 | /* Associates given parameters with a description. */ |
1680 | unsigned port; |
1681 | unsigned device; |
1682 | unsigned index; |
1683 | unsigned id; |
1684 | |
1685 | /* Human readable description for parameters. |
1686 | * The pointer must remain valid until |
1687 | * retro_unload_game() is called. */ |
1688 | const char *description; |
1689 | }; |
1690 | |
1691 | struct retro_system_info |
1692 | { |
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; |
1725 | }; |
1726 | |
1727 | struct retro_game_geometry |
1728 | { |
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. */ |
1739 | }; |
1740 | |
1741 | struct retro_system_timing |
1742 | { |
1743 | double fps; /* FPS of video content. */ |
1744 | double sample_rate; /* Sampling rate of audio. */ |
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 | { |
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; |
1766 | }; |
1767 | |
1768 | struct retro_game_info |
1769 | { |
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. */ |
1780 | }; |
1781 | |
1782 | /* Callbacks */ |
1783 | |
1784 | /* Environment callback. Gives implementations a way of performing |
1785 | * uncommon tasks. Extensible. */ |
1786 | typedef bool (*retro_environment_t)(unsigned cmd, void *data); |
1787 | |
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); |
1801 | |
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 | */ |
1806 | typedef void (*retro_audio_sample_t)(int16_t left, int16_t right); |
1807 | |
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. */ |
1818 | typedef void (*retro_input_poll_t)(void); |
1819 | |
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. */ |
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 | |
1842 | /* Library global initialization/deinitialization. */ |
1843 | void retro_init(void); |
1844 | void retro_deinit(void); |
1845 | |
1846 | /* Must return RETRO_API_VERSION. Used to validate ABI compatibility |
1847 | * when the API is revised. */ |
1848 | unsigned retro_api_version(void); |
1849 | |
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(). */ |
1853 | void retro_get_system_info(struct retro_system_info *info); |
1854 | |
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. */ |
1861 | void retro_get_system_av_info(struct retro_system_av_info *info); |
1862 | |
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. */ |
1871 | void retro_set_controller_port_device(unsigned port, unsigned device); |
1872 | |
1873 | /* Resets the current game. */ |
1874 | void retro_reset(void); |
1875 | |
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 | */ |
1884 | void retro_run(void); |
1885 | |
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 | */ |
1892 | size_t retro_serialize_size(void); |
1893 | |
1894 | /* Serializes internal state. If failed, or size is lower than |
1895 | * retro_serialize_size(), it should return false, true otherwise. */ |
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 | |
1902 | /* Loads a game. */ |
1903 | bool retro_load_game(const struct retro_game_info *game); |
1904 | |
1905 | /* Loads a "special" kind of game. Should not be used, |
1906 | * except in extreme cases. */ |
1907 | bool retro_load_game_special( |
1908 | unsigned game_type, |
1909 | const struct retro_game_info *info, size_t num_info |
1910 | ); |
1911 | |
1912 | /* Unloads a currently loaded game. */ |
1913 | void retro_unload_game(void); |
1914 | |
1915 | /* Gets region of game. */ |
1916 | unsigned retro_get_region(void); |
1917 | |
1918 | /* Gets region of memory. */ |
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 |