Commit | Line | Data |
---|---|---|
38c2028e | 1 | #ifndef LIBRETRO_H__ |
2 | #define LIBRETRO_H__ | |
3 | ||
4 | #include <stdint.h> | |
5 | #include <stddef.h> | |
c19aba43 | 6 | #include <limits.h> |
38c2028e | 7 | |
c19aba43 | 8 | // Hack applied for MSVC when compiling in C89 mode as it isn't C99 compliant. |
38c2028e | 9 | #ifdef __cplusplus |
10 | extern "C" { | |
11 | #else | |
c19aba43 | 12 | #if defined(_MSC_VER) && !defined(SN_TARGET_PS3) && !defined(__cplusplus) |
38c2028e | 13 | #define bool unsigned char |
14 | #define true 1 | |
15 | #define false 0 | |
16 | #else | |
17 | #include <stdbool.h> | |
18 | #endif | |
19 | #endif | |
20 | ||
c19aba43 | 21 | // Used for checking API/ABI mismatches that can break libretro implementations. |
23ea11bd | 22 | // It is not incremented for compatible changes to the API. |
38c2028e | 23 | #define RETRO_API_VERSION 1 |
24 | ||
c19aba43 | 25 | // Libretro's fundamental device abstractions. |
38c2028e | 26 | #define RETRO_DEVICE_MASK 0xff |
27 | #define RETRO_DEVICE_NONE 0 | |
c19aba43 TK |
28 | |
29 | // The JOYPAD is called RetroPad. It is essentially a Super Nintendo controller, | |
30 | // but with additional L2/R2/L3/R3 buttons, similar to a PS1 DualShock. | |
38c2028e | 31 | #define RETRO_DEVICE_JOYPAD 1 |
c19aba43 TK |
32 | |
33 | // The mouse is a simple mouse, similar to Super Nintendo's mouse. | |
34 | // X and Y coordinates are reported relatively to last poll (poll callback). | |
35 | // It is up to the libretro implementation to keep track of where the mouse pointer is supposed to be on the screen. | |
36 | // The frontend must make sure not to interfere with its own hardware mouse pointer. | |
38c2028e | 37 | #define RETRO_DEVICE_MOUSE 2 |
c19aba43 TK |
38 | |
39 | // KEYBOARD device lets one poll for raw key pressed. | |
40 | // It is poll based, so input callback will return with the current pressed state. | |
38c2028e | 41 | #define RETRO_DEVICE_KEYBOARD 3 |
c19aba43 TK |
42 | |
43 | // Lightgun X/Y coordinates are reported relatively to last poll, similar to mouse. | |
38c2028e | 44 | #define RETRO_DEVICE_LIGHTGUN 4 |
c19aba43 TK |
45 | |
46 | // The ANALOG device is an extension to JOYPAD (RetroPad). | |
47 | // Similar to DualShock it adds two analog sticks. | |
48 | // This is treated as a separate device type as it returns values in the full analog range | |
49 | // of [-0x8000, 0x7fff]. Positive X axis is right. Positive Y axis is down. | |
50 | // Only use ANALOG type when polling for analog values of the axes. | |
38c2028e | 51 | #define RETRO_DEVICE_ANALOG 5 |
52 | ||
23ea11bd | 53 | // Abstracts the concept of a pointing mechanism, e.g. touch. |
54 | // This allows libretro to query in absolute coordinates where on the screen a mouse (or something similar) is being placed. | |
55 | // For a touch centric device, coordinates reported are the coordinates of the press. | |
56 | // | |
57 | // Coordinates in X and Y are reported as: | |
58 | // [-0x7fff, 0x7fff]: -0x7fff corresponds to the far left/top of the screen, | |
59 | // and 0x7fff corresponds to the far right/bottom of the screen. | |
60 | // The "screen" is here defined as area that is passed to the frontend and later displayed on the monitor. | |
61 | // The frontend is free to scale/resize this screen as it sees fit, however, | |
62 | // (X, Y) = (-0x7fff, -0x7fff) will correspond to the top-left pixel of the game image, etc. | |
63 | // | |
64 | // To check if the pointer coordinates are valid (e.g. a touch display actually being touched), | |
65 | // PRESSED returns 1 or 0. | |
66 | // If using a mouse, PRESSED will usually correspond to the left mouse button. | |
67 | // PRESSED will only return 1 if the pointer is inside the game screen. | |
68 | // | |
69 | // For multi-touch, the index variable can be used to successively query more presses. | |
70 | // If index = 0 returns true for _PRESSED, coordinates can be extracted | |
71 | // with _X, _Y for index = 0. One can then query _PRESSED, _X, _Y with index = 1, and so on. | |
72 | // Eventually _PRESSED will return false for an index. No further presses are registered at this point. | |
73 | #define RETRO_DEVICE_POINTER 6 | |
74 | ||
c19aba43 TK |
75 | // These device types are specializations of the base types above. |
76 | // They should only be used in retro_set_controller_type() to inform libretro implementations | |
77 | // about use of a very specific device type. | |
78 | // | |
79 | // In input state callback, however, only the base type should be used in the 'device' field. | |
38c2028e | 80 | #define RETRO_DEVICE_JOYPAD_MULTITAP ((1 << 8) | RETRO_DEVICE_JOYPAD) |
81 | #define RETRO_DEVICE_LIGHTGUN_SUPER_SCOPE ((1 << 8) | RETRO_DEVICE_LIGHTGUN) | |
82 | #define RETRO_DEVICE_LIGHTGUN_JUSTIFIER ((2 << 8) | RETRO_DEVICE_LIGHTGUN) | |
83 | #define RETRO_DEVICE_LIGHTGUN_JUSTIFIERS ((3 << 8) | RETRO_DEVICE_LIGHTGUN) | |
84 | ||
c19aba43 TK |
85 | // Buttons for the RetroPad (JOYPAD). |
86 | // The placement of these is equivalent to placements on the Super Nintendo controller. | |
87 | // L2/R2/L3/R3 buttons correspond to the PS1 DualShock. | |
38c2028e | 88 | #define RETRO_DEVICE_ID_JOYPAD_B 0 |
89 | #define RETRO_DEVICE_ID_JOYPAD_Y 1 | |
90 | #define RETRO_DEVICE_ID_JOYPAD_SELECT 2 | |
91 | #define RETRO_DEVICE_ID_JOYPAD_START 3 | |
92 | #define RETRO_DEVICE_ID_JOYPAD_UP 4 | |
93 | #define RETRO_DEVICE_ID_JOYPAD_DOWN 5 | |
94 | #define RETRO_DEVICE_ID_JOYPAD_LEFT 6 | |
95 | #define RETRO_DEVICE_ID_JOYPAD_RIGHT 7 | |
96 | #define RETRO_DEVICE_ID_JOYPAD_A 8 | |
97 | #define RETRO_DEVICE_ID_JOYPAD_X 9 | |
98 | #define RETRO_DEVICE_ID_JOYPAD_L 10 | |
99 | #define RETRO_DEVICE_ID_JOYPAD_R 11 | |
100 | #define RETRO_DEVICE_ID_JOYPAD_L2 12 | |
101 | #define RETRO_DEVICE_ID_JOYPAD_R2 13 | |
102 | #define RETRO_DEVICE_ID_JOYPAD_L3 14 | |
103 | #define RETRO_DEVICE_ID_JOYPAD_R3 15 | |
104 | ||
c19aba43 | 105 | // Index / Id values for ANALOG device. |
38c2028e | 106 | #define RETRO_DEVICE_INDEX_ANALOG_LEFT 0 |
107 | #define RETRO_DEVICE_INDEX_ANALOG_RIGHT 1 | |
108 | #define RETRO_DEVICE_ID_ANALOG_X 0 | |
109 | #define RETRO_DEVICE_ID_ANALOG_Y 1 | |
110 | ||
c19aba43 | 111 | // Id values for MOUSE. |
38c2028e | 112 | #define RETRO_DEVICE_ID_MOUSE_X 0 |
113 | #define RETRO_DEVICE_ID_MOUSE_Y 1 | |
114 | #define RETRO_DEVICE_ID_MOUSE_LEFT 2 | |
115 | #define RETRO_DEVICE_ID_MOUSE_RIGHT 3 | |
116 | ||
c19aba43 | 117 | // Id values for LIGHTGUN types. |
38c2028e | 118 | #define RETRO_DEVICE_ID_LIGHTGUN_X 0 |
119 | #define RETRO_DEVICE_ID_LIGHTGUN_Y 1 | |
120 | #define RETRO_DEVICE_ID_LIGHTGUN_TRIGGER 2 | |
121 | #define RETRO_DEVICE_ID_LIGHTGUN_CURSOR 3 | |
122 | #define RETRO_DEVICE_ID_LIGHTGUN_TURBO 4 | |
123 | #define RETRO_DEVICE_ID_LIGHTGUN_PAUSE 5 | |
124 | #define RETRO_DEVICE_ID_LIGHTGUN_START 6 | |
125 | ||
23ea11bd | 126 | // Id values for POINTER. |
127 | #define RETRO_DEVICE_ID_POINTER_X 0 | |
128 | #define RETRO_DEVICE_ID_POINTER_Y 1 | |
129 | #define RETRO_DEVICE_ID_POINTER_PRESSED 2 | |
130 | ||
c19aba43 | 131 | // Returned from retro_get_region(). |
38c2028e | 132 | #define RETRO_REGION_NTSC 0 |
133 | #define RETRO_REGION_PAL 1 | |
134 | ||
c19aba43 TK |
135 | // Passed to retro_get_memory_data/size(). |
136 | // If the memory type doesn't apply to the implementation NULL/0 can be returned. | |
38c2028e | 137 | #define RETRO_MEMORY_MASK 0xff |
c19aba43 TK |
138 | |
139 | // Regular save ram. This ram is usually found on a game cartridge, backed up by a battery. | |
140 | // If save game data is too complex for a single memory buffer, | |
141 | // the SYSTEM_DIRECTORY environment callback can be used. | |
38c2028e | 142 | #define RETRO_MEMORY_SAVE_RAM 0 |
c19aba43 TK |
143 | |
144 | // Some games have a built-in clock to keep track of time. | |
145 | // This memory is usually just a couple of bytes to keep track of time. | |
38c2028e | 146 | #define RETRO_MEMORY_RTC 1 |
c19aba43 TK |
147 | |
148 | // System ram lets a frontend peek into a game systems main RAM. | |
38c2028e | 149 | #define RETRO_MEMORY_SYSTEM_RAM 2 |
c19aba43 TK |
150 | |
151 | // Video ram lets a frontend peek into a game systems video RAM (VRAM). | |
38c2028e | 152 | #define RETRO_MEMORY_VIDEO_RAM 3 |
153 | ||
c19aba43 | 154 | // Special memory types. |
38c2028e | 155 | #define RETRO_MEMORY_SNES_BSX_RAM ((1 << 8) | RETRO_MEMORY_SAVE_RAM) |
156 | #define RETRO_MEMORY_SNES_BSX_PRAM ((2 << 8) | RETRO_MEMORY_SAVE_RAM) | |
157 | #define RETRO_MEMORY_SNES_SUFAMI_TURBO_A_RAM ((3 << 8) | RETRO_MEMORY_SAVE_RAM) | |
158 | #define RETRO_MEMORY_SNES_SUFAMI_TURBO_B_RAM ((4 << 8) | RETRO_MEMORY_SAVE_RAM) | |
159 | #define RETRO_MEMORY_SNES_GAME_BOY_RAM ((5 << 8) | RETRO_MEMORY_SAVE_RAM) | |
160 | #define RETRO_MEMORY_SNES_GAME_BOY_RTC ((6 << 8) | RETRO_MEMORY_RTC) | |
161 | ||
c19aba43 TK |
162 | // Special game types passed into retro_load_game_special(). |
163 | // Only used when multiple ROMs are required. | |
38c2028e | 164 | #define RETRO_GAME_TYPE_BSX 0x101 |
165 | #define RETRO_GAME_TYPE_BSX_SLOTTED 0x102 | |
166 | #define RETRO_GAME_TYPE_SUFAMI_TURBO 0x103 | |
167 | #define RETRO_GAME_TYPE_SUPER_GAME_BOY 0x104 | |
168 | ||
c19aba43 TK |
169 | // Keysyms used for ID in input state callback when polling RETRO_KEYBOARD. |
170 | enum retro_key | |
171 | { | |
172 | RETROK_UNKNOWN = 0, | |
173 | RETROK_FIRST = 0, | |
174 | RETROK_BACKSPACE = 8, | |
175 | RETROK_TAB = 9, | |
176 | RETROK_CLEAR = 12, | |
177 | RETROK_RETURN = 13, | |
178 | RETROK_PAUSE = 19, | |
179 | RETROK_ESCAPE = 27, | |
180 | RETROK_SPACE = 32, | |
181 | RETROK_EXCLAIM = 33, | |
182 | RETROK_QUOTEDBL = 34, | |
183 | RETROK_HASH = 35, | |
184 | RETROK_DOLLAR = 36, | |
185 | RETROK_AMPERSAND = 38, | |
186 | RETROK_QUOTE = 39, | |
187 | RETROK_LEFTPAREN = 40, | |
188 | RETROK_RIGHTPAREN = 41, | |
189 | RETROK_ASTERISK = 42, | |
190 | RETROK_PLUS = 43, | |
191 | RETROK_COMMA = 44, | |
192 | RETROK_MINUS = 45, | |
193 | RETROK_PERIOD = 46, | |
194 | RETROK_SLASH = 47, | |
195 | RETROK_0 = 48, | |
196 | RETROK_1 = 49, | |
197 | RETROK_2 = 50, | |
198 | RETROK_3 = 51, | |
199 | RETROK_4 = 52, | |
200 | RETROK_5 = 53, | |
201 | RETROK_6 = 54, | |
202 | RETROK_7 = 55, | |
203 | RETROK_8 = 56, | |
204 | RETROK_9 = 57, | |
205 | RETROK_COLON = 58, | |
206 | RETROK_SEMICOLON = 59, | |
207 | RETROK_LESS = 60, | |
208 | RETROK_EQUALS = 61, | |
209 | RETROK_GREATER = 62, | |
210 | RETROK_QUESTION = 63, | |
211 | RETROK_AT = 64, | |
212 | RETROK_LEFTBRACKET = 91, | |
213 | RETROK_BACKSLASH = 92, | |
214 | RETROK_RIGHTBRACKET = 93, | |
215 | RETROK_CARET = 94, | |
216 | RETROK_UNDERSCORE = 95, | |
217 | RETROK_BACKQUOTE = 96, | |
218 | RETROK_a = 97, | |
219 | RETROK_b = 98, | |
220 | RETROK_c = 99, | |
221 | RETROK_d = 100, | |
222 | RETROK_e = 101, | |
223 | RETROK_f = 102, | |
224 | RETROK_g = 103, | |
225 | RETROK_h = 104, | |
226 | RETROK_i = 105, | |
227 | RETROK_j = 106, | |
228 | RETROK_k = 107, | |
229 | RETROK_l = 108, | |
230 | RETROK_m = 109, | |
231 | RETROK_n = 110, | |
232 | RETROK_o = 111, | |
233 | RETROK_p = 112, | |
234 | RETROK_q = 113, | |
235 | RETROK_r = 114, | |
236 | RETROK_s = 115, | |
237 | RETROK_t = 116, | |
238 | RETROK_u = 117, | |
239 | RETROK_v = 118, | |
240 | RETROK_w = 119, | |
241 | RETROK_x = 120, | |
242 | RETROK_y = 121, | |
243 | RETROK_z = 122, | |
244 | RETROK_DELETE = 127, | |
245 | ||
246 | RETROK_KP0 = 256, | |
247 | RETROK_KP1 = 257, | |
248 | RETROK_KP2 = 258, | |
249 | RETROK_KP3 = 259, | |
250 | RETROK_KP4 = 260, | |
251 | RETROK_KP5 = 261, | |
252 | RETROK_KP6 = 262, | |
253 | RETROK_KP7 = 263, | |
254 | RETROK_KP8 = 264, | |
255 | RETROK_KP9 = 265, | |
256 | RETROK_KP_PERIOD = 266, | |
257 | RETROK_KP_DIVIDE = 267, | |
258 | RETROK_KP_MULTIPLY = 268, | |
259 | RETROK_KP_MINUS = 269, | |
260 | RETROK_KP_PLUS = 270, | |
261 | RETROK_KP_ENTER = 271, | |
262 | RETROK_KP_EQUALS = 272, | |
263 | ||
264 | RETROK_UP = 273, | |
265 | RETROK_DOWN = 274, | |
266 | RETROK_RIGHT = 275, | |
267 | RETROK_LEFT = 276, | |
268 | RETROK_INSERT = 277, | |
269 | RETROK_HOME = 278, | |
270 | RETROK_END = 279, | |
271 | RETROK_PAGEUP = 280, | |
272 | RETROK_PAGEDOWN = 281, | |
273 | ||
274 | RETROK_F1 = 282, | |
275 | RETROK_F2 = 283, | |
276 | RETROK_F3 = 284, | |
277 | RETROK_F4 = 285, | |
278 | RETROK_F5 = 286, | |
279 | RETROK_F6 = 287, | |
280 | RETROK_F7 = 288, | |
281 | RETROK_F8 = 289, | |
282 | RETROK_F9 = 290, | |
283 | RETROK_F10 = 291, | |
284 | RETROK_F11 = 292, | |
285 | RETROK_F12 = 293, | |
286 | RETROK_F13 = 294, | |
287 | RETROK_F14 = 295, | |
288 | RETROK_F15 = 296, | |
289 | ||
290 | RETROK_NUMLOCK = 300, | |
291 | RETROK_CAPSLOCK = 301, | |
292 | RETROK_SCROLLOCK = 302, | |
293 | RETROK_RSHIFT = 303, | |
294 | RETROK_LSHIFT = 304, | |
295 | RETROK_RCTRL = 305, | |
296 | RETROK_LCTRL = 306, | |
297 | RETROK_RALT = 307, | |
298 | RETROK_LALT = 308, | |
299 | RETROK_RMETA = 309, | |
300 | RETROK_LMETA = 310, | |
301 | RETROK_LSUPER = 311, | |
302 | RETROK_RSUPER = 312, | |
303 | RETROK_MODE = 313, | |
304 | RETROK_COMPOSE = 314, | |
305 | ||
306 | RETROK_HELP = 315, | |
307 | RETROK_PRINT = 316, | |
308 | RETROK_SYSREQ = 317, | |
309 | RETROK_BREAK = 318, | |
310 | RETROK_MENU = 319, | |
311 | RETROK_POWER = 320, | |
312 | RETROK_EURO = 321, | |
313 | RETROK_UNDO = 322, | |
314 | ||
23ea11bd | 315 | RETROK_LAST, |
316 | ||
317 | RETROK_DUMMY = INT_MAX // Ensure sizeof(enum) == sizeof(int) | |
318 | }; | |
319 | ||
320 | enum retro_mod | |
321 | { | |
322 | RETROKMOD_NONE = 0x0000, | |
323 | ||
324 | RETROKMOD_SHIFT = 0x01, | |
325 | RETROKMOD_CTRL = 0x02, | |
326 | RETROKMOD_ALT = 0x04, | |
327 | RETROKMOD_META = 0x08, | |
328 | ||
329 | RETROKMOD_NUMLOCK = 0x10, | |
330 | RETROKMOD_CAPSLOCK = 0x20, | |
331 | RETROKMOD_SCROLLOCK = 0x40, | |
332 | ||
333 | RETROKMOD_DUMMY = INT_MAX // Ensure sizeof(enum) == sizeof(int) | |
c19aba43 | 334 | }; |
38c2028e | 335 | |
e56b1300 | 336 | // If set, this call is not part of the public libretro API yet. It can change or be removed at any time. |
337 | #define RETRO_ENVIRONMENT_EXPERIMENTAL 0x10000 | |
23ea11bd | 338 | |
38c2028e | 339 | // Environment commands. |
340 | #define RETRO_ENVIRONMENT_SET_ROTATION 1 // const unsigned * -- | |
341 | // Sets screen rotation of graphics. | |
342 | // Is only implemented if rotation can be accelerated by hardware. | |
343 | // Valid values are 0, 1, 2, 3, which rotates screen by 0, 90, 180, 270 degrees | |
344 | // counter-clockwise respectively. | |
345 | // | |
346 | #define RETRO_ENVIRONMENT_GET_OVERSCAN 2 // bool * -- | |
347 | // Boolean value whether or not the implementation should use overscan, or crop away overscan. | |
348 | // | |
349 | #define RETRO_ENVIRONMENT_GET_CAN_DUPE 3 // bool * -- | |
c19aba43 | 350 | // Boolean value whether or not frontend supports frame duping, |
38c2028e | 351 | // passing NULL to video frame callback. |
352 | // | |
e56b1300 | 353 | // Environ 4, 5 are no longer supported (GET_VARIABLE / SET_VARIABLES), and reserved to avoid possible ABI clash. |
38c2028e | 354 | #define RETRO_ENVIRONMENT_SET_MESSAGE 6 // const struct retro_message * -- |
355 | // Sets a message to be displayed in implementation-specific manner for a certain amount of 'frames'. | |
356 | // Should not be used for trivial messages, which should simply be logged to stderr. | |
357 | #define RETRO_ENVIRONMENT_SHUTDOWN 7 // N/A (NULL) -- | |
358 | // Requests the frontend to shutdown. | |
359 | // Should only be used if game has a specific | |
360 | // way to shutdown the game from a menu item or similar. | |
361 | // | |
362 | #define RETRO_ENVIRONMENT_SET_PERFORMANCE_LEVEL 8 | |
363 | // const unsigned * -- | |
364 | // Gives a hint to the frontend how demanding this implementation | |
365 | // is on a system. E.g. reporting a level of 2 means | |
366 | // this implementation should run decently on all frontends | |
367 | // of level 2 and up. | |
368 | // | |
369 | // It can be used by the frontend to potentially warn | |
370 | // about too demanding implementations. | |
23ea11bd | 371 | // |
38c2028e | 372 | // The levels are "floating", but roughly defined as: |
c19aba43 TK |
373 | // 0: Low-powered embedded devices such as Raspberry Pi |
374 | // 1: 6th generation consoles, such as Wii/Xbox 1, and phones, tablets, etc. | |
375 | // 2: 7th generation consoles, such as PS3/360, with sub-par CPUs. | |
38c2028e | 376 | // 3: Modern desktop/laptops with reasonably powerful CPUs. |
377 | // 4: High-end desktops with very powerful CPUs. | |
378 | // | |
379 | // This function can be called on a per-game basis, | |
380 | // as certain games an implementation can play might be | |
381 | // particularily demanding. | |
382 | // If called, it should be called in retro_load_game(). | |
383 | // | |
384 | #define RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY 9 | |
385 | // const char ** -- | |
386 | // Returns the "system" directory of the frontend. | |
387 | // This directory can be used to store system specific ROMs such as BIOSes, configuration data, etc. | |
388 | // The returned value can be NULL. | |
389 | // If so, no such directory is defined, | |
390 | // and it's up to the implementation to find a suitable directory. | |
391 | // | |
392 | #define RETRO_ENVIRONMENT_SET_PIXEL_FORMAT 10 | |
393 | // const enum retro_pixel_format * -- | |
394 | // Sets the internal pixel format used by the implementation. | |
c19aba43 TK |
395 | // The default pixel format is RETRO_PIXEL_FORMAT_0RGB1555. |
396 | // This pixel format however, is deprecated (see enum retro_pixel_format). | |
38c2028e | 397 | // If the call returns false, the frontend does not support this pixel format. |
398 | // This function should be called inside retro_load_game() or retro_get_system_av_info(). | |
c19aba43 TK |
399 | // |
400 | #define RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS 11 | |
401 | // const struct retro_input_descriptor * -- | |
402 | // Sets an array of retro_input_descriptors. | |
403 | // It is up to the frontend to present this in a usable way. | |
404 | // The array is terminated by retro_input_descriptor::description being set to NULL. | |
405 | // This function can be called at any time, but it is recommended to call it as early as possible. | |
23ea11bd | 406 | #define RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK 12 |
407 | // const struct retro_keyboard_callback * -- | |
408 | // Sets a callback function used to notify core about keyboard events. | |
409 | // | |
410 | #define RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE 13 | |
411 | // const struct retro_disk_control_callback * -- | |
412 | // Sets an interface which frontend can use to eject and insert disk images. | |
413 | // This is used for games which consist of multiple images and must be manually | |
414 | // swapped out by the user (e.g. PSX). | |
e56b1300 | 415 | #define RETRO_ENVIRONMENT_SET_HW_RENDER (14 | RETRO_ENVIRONMENT_EXPERIMENTAL) |
416 | // struct retro_hw_render_callback * -- | |
417 | // NOTE: This call is currently very experimental, and should not be considered part of the public API. | |
418 | // The interface could be changed or removed at any time. | |
419 | // Sets an interface to let a libretro core render with hardware acceleration. | |
420 | // Should be called in retro_load_game(). | |
421 | // If successful, libretro cores will be able to render to a frontend-provided framebuffer. | |
422 | // The size of this framebuffer will be at least as large as max_width/max_height provided in get_av_info(). | |
423 | // If HW rendering is used, pass only RETRO_HW_FRAME_BUFFER_VALID or NULL to retro_video_refresh_t. | |
424 | #define RETRO_ENVIRONMENT_GET_VARIABLE 15 | |
425 | // struct retro_variable * -- | |
426 | // Interface to aquire user-defined information from environment | |
427 | // that cannot feasibly be supported in a multi-system way. | |
428 | // 'key' should be set to a key which has already been set by SET_VARIABLES. | |
429 | // 'data' will be set to a value or NULL. | |
430 | // | |
431 | #define RETRO_ENVIRONMENT_SET_VARIABLES 16 | |
432 | // const struct retro_variable * -- | |
433 | // Allows an implementation to signal the environment | |
434 | // which variables it might want to check for later using GET_VARIABLE. | |
435 | // This allows the frontend to present these variables to a user dynamically. | |
436 | // This should be called as early as possible (ideally in retro_set_environment). | |
437 | // | |
438 | // 'data' points to an array of retro_variable structs terminated by a { NULL, NULL } element. | |
439 | // retro_variable::key should be namespaced to not collide with other implementations' keys. E.g. A core called 'foo' should use keys named as 'foo_option'. | |
440 | // retro_variable::value should contain a human readable description of the key as well as a '|' delimited list of expected values. | |
441 | // The number of possible options should be very limited, i.e. it should be feasible to cycle through options without a keyboard. | |
442 | // First entry should be treated as a default. | |
443 | // | |
444 | // Example entry: | |
445 | // { "foo_option", "Speed hack coprocessor X; false|true" } | |
446 | // | |
447 | // Text before first ';' is description. This ';' must be followed by a space, and followed by a list of possible values split up with '|'. | |
448 | // Only strings are operated on. The possible values will generally be displayed and stored as-is by the frontend. | |
449 | // | |
450 | #define RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE 17 | |
451 | // bool * -- | |
452 | // Result is set to true if some variables are updated by | |
453 | // frontend since last call to RETRO_ENVIRONMENT_GET_VARIABLE. | |
454 | // Variables should be queried with GET_VARIABLE. | |
6b5beb44 | 455 | // |
456 | #define RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME 18 | |
457 | // const bool * -- | |
458 | // If true, the libretro implementation supports calls to retro_load_game() with NULL as argument. | |
459 | // Used by cores which can run without particular game data. | |
460 | // This should be called within retro_set_environment() only. | |
461 | ||
e56b1300 | 462 | |
463 | // Pass this to retro_video_refresh_t if rendering to hardware. | |
464 | // Passing NULL to retro_video_refresh_t is still a frame dupe as normal. | |
465 | #define RETRO_HW_FRAME_BUFFER_VALID ((void*)-1) | |
466 | ||
467 | // Invalidates the current HW context. | |
468 | // If called, all GPU resources must be reinitialized. | |
469 | // Usually called when frontend reinits video driver. | |
470 | // Also called first time video driver is initialized, allowing libretro core to init resources. | |
471 | typedef void (*retro_hw_context_reset_t)(void); | |
472 | // Gets current framebuffer which is to be rendered to. Could change every frame potentially. | |
473 | typedef uintptr_t (*retro_hw_get_current_framebuffer_t)(void); | |
474 | ||
475 | // Get a symbol from HW context. | |
476 | typedef void (*retro_proc_address_t)(void); | |
477 | typedef retro_proc_address_t (*retro_hw_get_proc_address_t)(const char *sym); | |
478 | ||
479 | enum retro_hw_context_type | |
480 | { | |
481 | RETRO_HW_CONTEXT_NONE = 0, | |
482 | RETRO_HW_CONTEXT_OPENGL, // OpenGL 2.x. Latest version available before 3.x+. | |
483 | RETRO_HW_CONTEXT_OPENGLES2, // GLES 2.0 | |
484 | ||
485 | RETRO_HW_CONTEXT_DUMMY = INT_MAX | |
486 | }; | |
23ea11bd | 487 | |
e56b1300 | 488 | struct retro_hw_render_callback |
489 | { | |
490 | enum retro_hw_context_type context_type; // Which API to use. Set by libretro core. | |
491 | retro_hw_context_reset_t context_reset; // Set by libretro core. | |
492 | retro_hw_get_current_framebuffer_t get_current_framebuffer; // Set by frontend. | |
493 | retro_hw_get_proc_address_t get_proc_address; // Set by frontend. | |
494 | bool depth; // Set if render buffers should have depth component attached. | |
495 | }; | |
c19aba43 | 496 | |
23ea11bd | 497 | // Callback type passed in RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK. Called by the frontend in response to keyboard events. |
498 | // down is set if the key is being pressed, or false if it is being released. | |
499 | // keycode is the RETROK value of the char. | |
500 | // character is the text character of the pressed key. (UTF-32). | |
501 | // key_modifiers is a set of RETROKMOD values or'ed together. | |
502 | typedef void (*retro_keyboard_event_t)(bool down, unsigned keycode, uint32_t character, uint16_t key_modifiers); | |
503 | ||
504 | struct retro_keyboard_callback | |
505 | { | |
6b5beb44 | 506 | retro_keyboard_event_t callback; |
23ea11bd | 507 | }; |
508 | ||
509 | // Callbacks for RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE. | |
510 | // Should be set for implementations which can swap out multiple disk images in runtime. | |
511 | // If the implementation can do this automatically, it should strive to do so. | |
512 | // However, there are cases where the user must manually do so. | |
513 | // | |
514 | // Overview: To swap a disk image, eject the disk image with set_eject_state(true). | |
515 | // Set the disk index with set_image_index(index). Insert the disk again with set_eject_state(false). | |
516 | ||
517 | // If ejected is true, "ejects" the virtual disk tray. | |
518 | // When ejected, the disk image index can be set. | |
519 | typedef bool (*retro_set_eject_state_t)(bool ejected); | |
520 | // Gets current eject state. The initial state is 'not ejected'. | |
521 | typedef bool (*retro_get_eject_state_t)(void); | |
522 | // Gets current disk index. First disk is index 0. | |
523 | // If return value is >= get_num_images(), no disk is currently inserted. | |
524 | typedef unsigned (*retro_get_image_index_t)(void); | |
525 | // Sets image index. Can only be called when disk is ejected. | |
526 | // The implementation supports setting "no disk" by using an index >= get_num_images(). | |
527 | typedef bool (*retro_set_image_index_t)(unsigned index); | |
528 | // Gets total number of images which are available to use. | |
529 | typedef unsigned (*retro_get_num_images_t)(void); | |
530 | // | |
531 | // Replaces the disk image associated with index. | |
532 | // Arguments to pass in info have same requirements as retro_load_game(). | |
533 | // Virtual disk tray must be ejected when calling this. | |
534 | // Replacing a disk image with info = NULL will remove the disk image from the internal list. | |
535 | // As a result, calls to get_image_index() can change. | |
536 | // | |
537 | // E.g. replace_image_index(1, NULL), and previous get_image_index() returned 4 before. | |
538 | // Index 1 will be removed, and the new index is 3. | |
539 | struct retro_game_info; | |
540 | typedef bool (*retro_replace_image_index_t)(unsigned index, const struct retro_game_info *info); | |
541 | // Adds a new valid index (get_num_images()) to the internal disk list. | |
542 | // This will increment subsequent return values from get_num_images() by 1. | |
543 | // This image index cannot be used until a disk image has been set with replace_image_index. | |
544 | typedef bool (*retro_add_image_index_t)(void); | |
545 | ||
546 | struct retro_disk_control_callback | |
547 | { | |
548 | retro_set_eject_state_t set_eject_state; | |
549 | retro_get_eject_state_t get_eject_state; | |
550 | ||
551 | retro_get_image_index_t get_image_index; | |
552 | retro_set_image_index_t set_image_index; | |
553 | retro_get_num_images_t get_num_images; | |
554 | ||
555 | retro_replace_image_index_t replace_image_index; | |
556 | retro_add_image_index_t add_image_index; | |
557 | }; | |
38c2028e | 558 | |
559 | enum retro_pixel_format | |
560 | { | |
c19aba43 TK |
561 | // 0RGB1555, native endian. 0 bit must be set to 0. |
562 | // This pixel format is default for compatibility concerns only. | |
563 | // If a 15/16-bit pixel format is desired, consider using RGB565. | |
564 | RETRO_PIXEL_FORMAT_0RGB1555 = 0, | |
565 | ||
566 | // XRGB8888, native endian. X bits are ignored. | |
567 | RETRO_PIXEL_FORMAT_XRGB8888 = 1, | |
568 | ||
569 | // RGB565, native endian. This pixel format is the recommended format to use if a 15/16-bit format is desired | |
570 | // as it is the pixel format that is typically available on a wide range of low-power devices. | |
571 | // It is also natively supported in APIs like OpenGL ES. | |
572 | RETRO_PIXEL_FORMAT_RGB565 = 2, | |
573 | ||
574 | // Ensure sizeof() == sizeof(int). | |
575 | RETRO_PIXEL_FORMAT_UNKNOWN = INT_MAX | |
38c2028e | 576 | }; |
577 | ||
578 | struct retro_message | |
579 | { | |
580 | const char *msg; // Message to be displayed. | |
581 | unsigned frames; // Duration in frames of message. | |
582 | }; | |
583 | ||
c19aba43 TK |
584 | // Describes how the libretro implementation maps a libretro input bind |
585 | // to its internal input system through a human readable string. | |
586 | // This string can be used to better let a user configure input. | |
587 | struct retro_input_descriptor | |
588 | { | |
589 | // Associates given parameters with a description. | |
590 | unsigned port; | |
591 | unsigned device; | |
592 | unsigned index; | |
593 | unsigned id; | |
594 | ||
595 | const char *description; // Human readable description for parameters. | |
596 | // The pointer must remain valid until retro_unload_game() is called. | |
597 | }; | |
598 | ||
38c2028e | 599 | struct retro_system_info |
600 | { | |
c19aba43 TK |
601 | // All pointers are owned by libretro implementation, and pointers must remain valid until retro_deinit() is called. |
602 | ||
38c2028e | 603 | const char *library_name; // Descriptive name of library. Should not contain any version numbers, etc. |
604 | const char *library_version; // Descriptive version of core. | |
605 | ||
606 | const char *valid_extensions; // A string listing probably rom extensions the core will be able to load, separated with pipe. | |
607 | // I.e. "bin|rom|iso". | |
608 | // Typically used for a GUI to filter out extensions. | |
609 | ||
610 | bool need_fullpath; // If true, retro_load_game() is guaranteed to provide a valid pathname in retro_game_info::path. | |
611 | // ::data and ::size are both invalid. | |
612 | // If false, ::data and ::size are guaranteed to be valid, but ::path might not be valid. | |
613 | // This is typically set to true for libretro implementations that must load from file. | |
614 | // Implementations should strive for setting this to false, as it allows the frontend to perform patching, etc. | |
615 | ||
616 | bool block_extract; // If true, the frontend is not allowed to extract any archives before loading the real ROM. | |
617 | // Necessary for certain libretro implementations that load games from zipped archives. | |
618 | }; | |
619 | ||
620 | struct retro_game_geometry | |
621 | { | |
622 | unsigned base_width; // Nominal video width of game. | |
623 | unsigned base_height; // Nominal video height of game. | |
624 | unsigned max_width; // Maximum possible width of game. | |
625 | unsigned max_height; // Maximum possible height of game. | |
626 | ||
627 | float aspect_ratio; // Nominal aspect ratio of game. If aspect_ratio is <= 0.0, | |
628 | // an aspect ratio of base_width / base_height is assumed. | |
629 | // A frontend could override this setting if desired. | |
630 | }; | |
631 | ||
632 | struct retro_system_timing | |
633 | { | |
634 | double fps; // FPS of video content. | |
635 | double sample_rate; // Sampling rate of audio. | |
636 | }; | |
637 | ||
638 | struct retro_system_av_info | |
639 | { | |
640 | struct retro_game_geometry geometry; | |
641 | struct retro_system_timing timing; | |
642 | }; | |
643 | ||
644 | struct retro_variable | |
645 | { | |
646 | const char *key; // Variable to query in RETRO_ENVIRONMENT_GET_VARIABLE. | |
647 | // If NULL, obtains the complete environment string if more complex parsing is necessary. | |
648 | // The environment string is formatted as key-value pairs delimited by semicolons as so: | |
649 | // "key1=value1;key2=value2;..." | |
650 | const char *value; // Value to be obtained. If key does not exist, it is set to NULL. | |
651 | }; | |
652 | ||
653 | struct retro_game_info | |
654 | { | |
655 | const char *path; // Path to game, UTF-8 encoded. Usually used as a reference. | |
656 | // May be NULL if rom was loaded from stdin or similar. | |
657 | // retro_system_info::need_fullpath guaranteed that this path is valid. | |
658 | const void *data; // Memory buffer of loaded game. Will be NULL if need_fullpath was set. | |
659 | size_t size; // Size of memory buffer. | |
660 | const char *meta; // String of implementation specific meta-data. | |
661 | }; | |
662 | ||
663 | // Callbacks | |
664 | // | |
665 | // Environment callback. Gives implementations a way of performing uncommon tasks. Extensible. | |
666 | typedef bool (*retro_environment_t)(unsigned cmd, void *data); | |
667 | ||
668 | // Render a frame. Pixel format is 15-bit 0RGB1555 native endian unless changed (see RETRO_ENVIRONMENT_SET_PIXEL_FORMAT). | |
669 | // Width and height specify dimensions of buffer. | |
670 | // Pitch specifices length in bytes between two lines in buffer. | |
c19aba43 TK |
671 | // For performance reasons, it is highly recommended to have a frame that is packed in memory, i.e. pitch == width * byte_per_pixel. |
672 | // Certain graphic APIs, such as OpenGL ES, do not like textures that are not packed in memory. | |
38c2028e | 673 | typedef void (*retro_video_refresh_t)(const void *data, unsigned width, unsigned height, size_t pitch); |
674 | ||
675 | // Renders a single audio frame. Should only be used if implementation generates a single sample at a time. | |
676 | // Format is signed 16-bit native endian. | |
677 | typedef void (*retro_audio_sample_t)(int16_t left, int16_t right); | |
678 | // Renders multiple audio frames in one go. One frame is defined as a sample of left and right channels, interleaved. | |
679 | // I.e. int16_t buf[4] = { l, r, l, r }; would be 2 frames. | |
680 | // Only one of the audio callbacks must ever be used. | |
681 | typedef size_t (*retro_audio_sample_batch_t)(const int16_t *data, size_t frames); | |
682 | ||
683 | // Polls input. | |
684 | typedef void (*retro_input_poll_t)(void); | |
685 | // Queries for input for player 'port'. device will be masked with RETRO_DEVICE_MASK. | |
686 | // Specialization of devices such as RETRO_DEVICE_JOYPAD_MULTITAP that have been set with retro_set_controller_port_device() | |
687 | // will still use the higher level RETRO_DEVICE_JOYPAD to request input. | |
688 | typedef int16_t (*retro_input_state_t)(unsigned port, unsigned device, unsigned index, unsigned id); | |
689 | ||
690 | // Sets callbacks. retro_set_environment() is guaranteed to be called before retro_init(). | |
691 | // The rest of the set_* functions are guaranteed to have been called before the first call to retro_run() is made. | |
692 | void retro_set_environment(retro_environment_t); | |
693 | void retro_set_video_refresh(retro_video_refresh_t); | |
694 | void retro_set_audio_sample(retro_audio_sample_t); | |
695 | void retro_set_audio_sample_batch(retro_audio_sample_batch_t); | |
696 | void retro_set_input_poll(retro_input_poll_t); | |
697 | void retro_set_input_state(retro_input_state_t); | |
698 | ||
699 | // Library global initialization/deinitialization. | |
700 | void retro_init(void); | |
701 | void retro_deinit(void); | |
702 | ||
703 | // Must return RETRO_API_VERSION. Used to validate ABI compatibility when the API is revised. | |
704 | unsigned retro_api_version(void); | |
705 | ||
706 | // Gets statically known system info. Pointers provided in *info must be statically allocated. | |
707 | // Can be called at any time, even before retro_init(). | |
708 | void retro_get_system_info(struct retro_system_info *info); | |
709 | ||
710 | // Gets information about system audio/video timings and geometry. | |
711 | // Can be called only after retro_load_game() has successfully completed. | |
c19aba43 TK |
712 | // NOTE: The implementation of this function might not initialize every variable if needed. |
713 | // E.g. geom.aspect_ratio might not be initialized if core doesn't desire a particular aspect ratio. | |
38c2028e | 714 | void retro_get_system_av_info(struct retro_system_av_info *info); |
715 | ||
716 | // Sets device to be used for player 'port'. | |
717 | void retro_set_controller_port_device(unsigned port, unsigned device); | |
718 | ||
719 | // Resets the current game. | |
720 | void retro_reset(void); | |
721 | ||
722 | // Runs the game for one video frame. | |
723 | // During retro_run(), input_poll callback must be called at least once. | |
724 | // | |
725 | // If a frame is not rendered for reasons where a game "dropped" a frame, | |
726 | // this still counts as a frame, and retro_run() should explicitly dupe a frame if GET_CAN_DUPE returns true. | |
727 | // In this case, the video callback can take a NULL argument for data. | |
728 | void retro_run(void); | |
729 | ||
730 | // Returns the amount of data the implementation requires to serialize internal state (save states). | |
731 | // Beetween calls to retro_load_game() and retro_unload_game(), the returned size is never allowed to be larger than a previous returned value, to | |
732 | // ensure that the frontend can allocate a save state buffer once. | |
733 | size_t retro_serialize_size(void); | |
734 | ||
735 | // Serializes internal state. If failed, or size is lower than retro_serialize_size(), it should return false, true otherwise. | |
736 | bool retro_serialize(void *data, size_t size); | |
737 | bool retro_unserialize(const void *data, size_t size); | |
738 | ||
739 | void retro_cheat_reset(void); | |
740 | void retro_cheat_set(unsigned index, bool enabled, const char *code); | |
741 | ||
742 | // Loads a game. | |
743 | bool retro_load_game(const struct retro_game_info *game); | |
744 | ||
745 | // Loads a "special" kind of game. Should not be used except in extreme cases. | |
746 | bool retro_load_game_special( | |
747 | unsigned game_type, | |
748 | const struct retro_game_info *info, size_t num_info | |
749 | ); | |
750 | ||
751 | // Unloads a currently loaded game. | |
752 | void retro_unload_game(void); | |
753 | ||
754 | // Gets region of game. | |
755 | unsigned retro_get_region(void); | |
756 | ||
757 | // Gets region of memory. | |
758 | void *retro_get_memory_data(unsigned id); | |
759 | size_t retro_get_memory_size(unsigned id); | |
760 | ||
761 | #ifdef __cplusplus | |
762 | } | |
763 | #endif | |
764 | ||
765 | #endif |