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 TK |
21 | // Used for checking API/ABI mismatches that can break libretro implementations. |
22 | // It is not incremented for compatible changes. | |
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 | ||
c19aba43 TK |
53 | // These device types are specializations of the base types above. |
54 | // They should only be used in retro_set_controller_type() to inform libretro implementations | |
55 | // about use of a very specific device type. | |
56 | // | |
57 | // In input state callback, however, only the base type should be used in the 'device' field. | |
38c2028e | 58 | #define RETRO_DEVICE_JOYPAD_MULTITAP ((1 << 8) | RETRO_DEVICE_JOYPAD) |
59 | #define RETRO_DEVICE_LIGHTGUN_SUPER_SCOPE ((1 << 8) | RETRO_DEVICE_LIGHTGUN) | |
60 | #define RETRO_DEVICE_LIGHTGUN_JUSTIFIER ((2 << 8) | RETRO_DEVICE_LIGHTGUN) | |
61 | #define RETRO_DEVICE_LIGHTGUN_JUSTIFIERS ((3 << 8) | RETRO_DEVICE_LIGHTGUN) | |
62 | ||
c19aba43 TK |
63 | // Buttons for the RetroPad (JOYPAD). |
64 | // The placement of these is equivalent to placements on the Super Nintendo controller. | |
65 | // L2/R2/L3/R3 buttons correspond to the PS1 DualShock. | |
38c2028e | 66 | #define RETRO_DEVICE_ID_JOYPAD_B 0 |
67 | #define RETRO_DEVICE_ID_JOYPAD_Y 1 | |
68 | #define RETRO_DEVICE_ID_JOYPAD_SELECT 2 | |
69 | #define RETRO_DEVICE_ID_JOYPAD_START 3 | |
70 | #define RETRO_DEVICE_ID_JOYPAD_UP 4 | |
71 | #define RETRO_DEVICE_ID_JOYPAD_DOWN 5 | |
72 | #define RETRO_DEVICE_ID_JOYPAD_LEFT 6 | |
73 | #define RETRO_DEVICE_ID_JOYPAD_RIGHT 7 | |
74 | #define RETRO_DEVICE_ID_JOYPAD_A 8 | |
75 | #define RETRO_DEVICE_ID_JOYPAD_X 9 | |
76 | #define RETRO_DEVICE_ID_JOYPAD_L 10 | |
77 | #define RETRO_DEVICE_ID_JOYPAD_R 11 | |
78 | #define RETRO_DEVICE_ID_JOYPAD_L2 12 | |
79 | #define RETRO_DEVICE_ID_JOYPAD_R2 13 | |
80 | #define RETRO_DEVICE_ID_JOYPAD_L3 14 | |
81 | #define RETRO_DEVICE_ID_JOYPAD_R3 15 | |
82 | ||
c19aba43 | 83 | // Index / Id values for ANALOG device. |
38c2028e | 84 | #define RETRO_DEVICE_INDEX_ANALOG_LEFT 0 |
85 | #define RETRO_DEVICE_INDEX_ANALOG_RIGHT 1 | |
86 | #define RETRO_DEVICE_ID_ANALOG_X 0 | |
87 | #define RETRO_DEVICE_ID_ANALOG_Y 1 | |
88 | ||
c19aba43 | 89 | // Id values for MOUSE. |
38c2028e | 90 | #define RETRO_DEVICE_ID_MOUSE_X 0 |
91 | #define RETRO_DEVICE_ID_MOUSE_Y 1 | |
92 | #define RETRO_DEVICE_ID_MOUSE_LEFT 2 | |
93 | #define RETRO_DEVICE_ID_MOUSE_RIGHT 3 | |
94 | ||
c19aba43 | 95 | // Id values for LIGHTGUN types. |
38c2028e | 96 | #define RETRO_DEVICE_ID_LIGHTGUN_X 0 |
97 | #define RETRO_DEVICE_ID_LIGHTGUN_Y 1 | |
98 | #define RETRO_DEVICE_ID_LIGHTGUN_TRIGGER 2 | |
99 | #define RETRO_DEVICE_ID_LIGHTGUN_CURSOR 3 | |
100 | #define RETRO_DEVICE_ID_LIGHTGUN_TURBO 4 | |
101 | #define RETRO_DEVICE_ID_LIGHTGUN_PAUSE 5 | |
102 | #define RETRO_DEVICE_ID_LIGHTGUN_START 6 | |
103 | ||
c19aba43 | 104 | // Returned from retro_get_region(). |
38c2028e | 105 | #define RETRO_REGION_NTSC 0 |
106 | #define RETRO_REGION_PAL 1 | |
107 | ||
c19aba43 TK |
108 | // Passed to retro_get_memory_data/size(). |
109 | // If the memory type doesn't apply to the implementation NULL/0 can be returned. | |
38c2028e | 110 | #define RETRO_MEMORY_MASK 0xff |
c19aba43 TK |
111 | |
112 | // Regular save ram. This ram is usually found on a game cartridge, backed up by a battery. | |
113 | // If save game data is too complex for a single memory buffer, | |
114 | // the SYSTEM_DIRECTORY environment callback can be used. | |
38c2028e | 115 | #define RETRO_MEMORY_SAVE_RAM 0 |
c19aba43 TK |
116 | |
117 | // Some games have a built-in clock to keep track of time. | |
118 | // This memory is usually just a couple of bytes to keep track of time. | |
38c2028e | 119 | #define RETRO_MEMORY_RTC 1 |
c19aba43 TK |
120 | |
121 | // System ram lets a frontend peek into a game systems main RAM. | |
38c2028e | 122 | #define RETRO_MEMORY_SYSTEM_RAM 2 |
c19aba43 TK |
123 | |
124 | // Video ram lets a frontend peek into a game systems video RAM (VRAM). | |
38c2028e | 125 | #define RETRO_MEMORY_VIDEO_RAM 3 |
126 | ||
c19aba43 | 127 | // Special memory types. |
38c2028e | 128 | #define RETRO_MEMORY_SNES_BSX_RAM ((1 << 8) | RETRO_MEMORY_SAVE_RAM) |
129 | #define RETRO_MEMORY_SNES_BSX_PRAM ((2 << 8) | RETRO_MEMORY_SAVE_RAM) | |
130 | #define RETRO_MEMORY_SNES_SUFAMI_TURBO_A_RAM ((3 << 8) | RETRO_MEMORY_SAVE_RAM) | |
131 | #define RETRO_MEMORY_SNES_SUFAMI_TURBO_B_RAM ((4 << 8) | RETRO_MEMORY_SAVE_RAM) | |
132 | #define RETRO_MEMORY_SNES_GAME_BOY_RAM ((5 << 8) | RETRO_MEMORY_SAVE_RAM) | |
133 | #define RETRO_MEMORY_SNES_GAME_BOY_RTC ((6 << 8) | RETRO_MEMORY_RTC) | |
134 | ||
c19aba43 TK |
135 | // Special game types passed into retro_load_game_special(). |
136 | // Only used when multiple ROMs are required. | |
38c2028e | 137 | #define RETRO_GAME_TYPE_BSX 0x101 |
138 | #define RETRO_GAME_TYPE_BSX_SLOTTED 0x102 | |
139 | #define RETRO_GAME_TYPE_SUFAMI_TURBO 0x103 | |
140 | #define RETRO_GAME_TYPE_SUPER_GAME_BOY 0x104 | |
141 | ||
c19aba43 TK |
142 | // Keysyms used for ID in input state callback when polling RETRO_KEYBOARD. |
143 | enum retro_key | |
144 | { | |
145 | RETROK_UNKNOWN = 0, | |
146 | RETROK_FIRST = 0, | |
147 | RETROK_BACKSPACE = 8, | |
148 | RETROK_TAB = 9, | |
149 | RETROK_CLEAR = 12, | |
150 | RETROK_RETURN = 13, | |
151 | RETROK_PAUSE = 19, | |
152 | RETROK_ESCAPE = 27, | |
153 | RETROK_SPACE = 32, | |
154 | RETROK_EXCLAIM = 33, | |
155 | RETROK_QUOTEDBL = 34, | |
156 | RETROK_HASH = 35, | |
157 | RETROK_DOLLAR = 36, | |
158 | RETROK_AMPERSAND = 38, | |
159 | RETROK_QUOTE = 39, | |
160 | RETROK_LEFTPAREN = 40, | |
161 | RETROK_RIGHTPAREN = 41, | |
162 | RETROK_ASTERISK = 42, | |
163 | RETROK_PLUS = 43, | |
164 | RETROK_COMMA = 44, | |
165 | RETROK_MINUS = 45, | |
166 | RETROK_PERIOD = 46, | |
167 | RETROK_SLASH = 47, | |
168 | RETROK_0 = 48, | |
169 | RETROK_1 = 49, | |
170 | RETROK_2 = 50, | |
171 | RETROK_3 = 51, | |
172 | RETROK_4 = 52, | |
173 | RETROK_5 = 53, | |
174 | RETROK_6 = 54, | |
175 | RETROK_7 = 55, | |
176 | RETROK_8 = 56, | |
177 | RETROK_9 = 57, | |
178 | RETROK_COLON = 58, | |
179 | RETROK_SEMICOLON = 59, | |
180 | RETROK_LESS = 60, | |
181 | RETROK_EQUALS = 61, | |
182 | RETROK_GREATER = 62, | |
183 | RETROK_QUESTION = 63, | |
184 | RETROK_AT = 64, | |
185 | RETROK_LEFTBRACKET = 91, | |
186 | RETROK_BACKSLASH = 92, | |
187 | RETROK_RIGHTBRACKET = 93, | |
188 | RETROK_CARET = 94, | |
189 | RETROK_UNDERSCORE = 95, | |
190 | RETROK_BACKQUOTE = 96, | |
191 | RETROK_a = 97, | |
192 | RETROK_b = 98, | |
193 | RETROK_c = 99, | |
194 | RETROK_d = 100, | |
195 | RETROK_e = 101, | |
196 | RETROK_f = 102, | |
197 | RETROK_g = 103, | |
198 | RETROK_h = 104, | |
199 | RETROK_i = 105, | |
200 | RETROK_j = 106, | |
201 | RETROK_k = 107, | |
202 | RETROK_l = 108, | |
203 | RETROK_m = 109, | |
204 | RETROK_n = 110, | |
205 | RETROK_o = 111, | |
206 | RETROK_p = 112, | |
207 | RETROK_q = 113, | |
208 | RETROK_r = 114, | |
209 | RETROK_s = 115, | |
210 | RETROK_t = 116, | |
211 | RETROK_u = 117, | |
212 | RETROK_v = 118, | |
213 | RETROK_w = 119, | |
214 | RETROK_x = 120, | |
215 | RETROK_y = 121, | |
216 | RETROK_z = 122, | |
217 | RETROK_DELETE = 127, | |
218 | ||
219 | RETROK_KP0 = 256, | |
220 | RETROK_KP1 = 257, | |
221 | RETROK_KP2 = 258, | |
222 | RETROK_KP3 = 259, | |
223 | RETROK_KP4 = 260, | |
224 | RETROK_KP5 = 261, | |
225 | RETROK_KP6 = 262, | |
226 | RETROK_KP7 = 263, | |
227 | RETROK_KP8 = 264, | |
228 | RETROK_KP9 = 265, | |
229 | RETROK_KP_PERIOD = 266, | |
230 | RETROK_KP_DIVIDE = 267, | |
231 | RETROK_KP_MULTIPLY = 268, | |
232 | RETROK_KP_MINUS = 269, | |
233 | RETROK_KP_PLUS = 270, | |
234 | RETROK_KP_ENTER = 271, | |
235 | RETROK_KP_EQUALS = 272, | |
236 | ||
237 | RETROK_UP = 273, | |
238 | RETROK_DOWN = 274, | |
239 | RETROK_RIGHT = 275, | |
240 | RETROK_LEFT = 276, | |
241 | RETROK_INSERT = 277, | |
242 | RETROK_HOME = 278, | |
243 | RETROK_END = 279, | |
244 | RETROK_PAGEUP = 280, | |
245 | RETROK_PAGEDOWN = 281, | |
246 | ||
247 | RETROK_F1 = 282, | |
248 | RETROK_F2 = 283, | |
249 | RETROK_F3 = 284, | |
250 | RETROK_F4 = 285, | |
251 | RETROK_F5 = 286, | |
252 | RETROK_F6 = 287, | |
253 | RETROK_F7 = 288, | |
254 | RETROK_F8 = 289, | |
255 | RETROK_F9 = 290, | |
256 | RETROK_F10 = 291, | |
257 | RETROK_F11 = 292, | |
258 | RETROK_F12 = 293, | |
259 | RETROK_F13 = 294, | |
260 | RETROK_F14 = 295, | |
261 | RETROK_F15 = 296, | |
262 | ||
263 | RETROK_NUMLOCK = 300, | |
264 | RETROK_CAPSLOCK = 301, | |
265 | RETROK_SCROLLOCK = 302, | |
266 | RETROK_RSHIFT = 303, | |
267 | RETROK_LSHIFT = 304, | |
268 | RETROK_RCTRL = 305, | |
269 | RETROK_LCTRL = 306, | |
270 | RETROK_RALT = 307, | |
271 | RETROK_LALT = 308, | |
272 | RETROK_RMETA = 309, | |
273 | RETROK_LMETA = 310, | |
274 | RETROK_LSUPER = 311, | |
275 | RETROK_RSUPER = 312, | |
276 | RETROK_MODE = 313, | |
277 | RETROK_COMPOSE = 314, | |
278 | ||
279 | RETROK_HELP = 315, | |
280 | RETROK_PRINT = 316, | |
281 | RETROK_SYSREQ = 317, | |
282 | RETROK_BREAK = 318, | |
283 | RETROK_MENU = 319, | |
284 | RETROK_POWER = 320, | |
285 | RETROK_EURO = 321, | |
286 | RETROK_UNDO = 322, | |
287 | ||
288 | RETROK_LAST | |
289 | }; | |
38c2028e | 290 | |
291 | // Environment commands. | |
292 | #define RETRO_ENVIRONMENT_SET_ROTATION 1 // const unsigned * -- | |
293 | // Sets screen rotation of graphics. | |
294 | // Is only implemented if rotation can be accelerated by hardware. | |
295 | // Valid values are 0, 1, 2, 3, which rotates screen by 0, 90, 180, 270 degrees | |
296 | // counter-clockwise respectively. | |
297 | // | |
298 | #define RETRO_ENVIRONMENT_GET_OVERSCAN 2 // bool * -- | |
299 | // Boolean value whether or not the implementation should use overscan, or crop away overscan. | |
300 | // | |
301 | #define RETRO_ENVIRONMENT_GET_CAN_DUPE 3 // bool * -- | |
c19aba43 | 302 | // Boolean value whether or not frontend supports frame duping, |
38c2028e | 303 | // passing NULL to video frame callback. |
304 | // | |
305 | #define RETRO_ENVIRONMENT_GET_VARIABLE 4 // struct retro_variable * -- | |
306 | // Interface to aquire user-defined information from environment | |
307 | // that cannot feasibly be supported in a multi-system way. | |
308 | // Mostly used for obscure, | |
309 | // specific features that the user can tap into when neseccary. | |
310 | // | |
311 | #define RETRO_ENVIRONMENT_SET_VARIABLES 5 // const struct retro_variable * -- | |
312 | // Allows an implementation to signal the environment | |
313 | // which variables it might want to check for later using GET_VARIABLE. | |
314 | // 'data' points to an array of retro_variable structs terminated by a { NULL, NULL } element. | |
315 | // retro_variable::value should contain a human readable description of the key. | |
316 | // | |
317 | #define RETRO_ENVIRONMENT_SET_MESSAGE 6 // const struct retro_message * -- | |
318 | // Sets a message to be displayed in implementation-specific manner for a certain amount of 'frames'. | |
319 | // Should not be used for trivial messages, which should simply be logged to stderr. | |
320 | #define RETRO_ENVIRONMENT_SHUTDOWN 7 // N/A (NULL) -- | |
321 | // Requests the frontend to shutdown. | |
322 | // Should only be used if game has a specific | |
323 | // way to shutdown the game from a menu item or similar. | |
324 | // | |
325 | #define RETRO_ENVIRONMENT_SET_PERFORMANCE_LEVEL 8 | |
326 | // const unsigned * -- | |
327 | // Gives a hint to the frontend how demanding this implementation | |
328 | // is on a system. E.g. reporting a level of 2 means | |
329 | // this implementation should run decently on all frontends | |
330 | // of level 2 and up. | |
331 | // | |
332 | // It can be used by the frontend to potentially warn | |
333 | // about too demanding implementations. | |
334 | // | |
335 | // The levels are "floating", but roughly defined as: | |
c19aba43 TK |
336 | // 0: Low-powered embedded devices such as Raspberry Pi |
337 | // 1: 6th generation consoles, such as Wii/Xbox 1, and phones, tablets, etc. | |
338 | // 2: 7th generation consoles, such as PS3/360, with sub-par CPUs. | |
38c2028e | 339 | // 3: Modern desktop/laptops with reasonably powerful CPUs. |
340 | // 4: High-end desktops with very powerful CPUs. | |
341 | // | |
342 | // This function can be called on a per-game basis, | |
343 | // as certain games an implementation can play might be | |
344 | // particularily demanding. | |
345 | // If called, it should be called in retro_load_game(). | |
346 | // | |
347 | #define RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY 9 | |
348 | // const char ** -- | |
349 | // Returns the "system" directory of the frontend. | |
350 | // This directory can be used to store system specific ROMs such as BIOSes, configuration data, etc. | |
351 | // The returned value can be NULL. | |
352 | // If so, no such directory is defined, | |
353 | // and it's up to the implementation to find a suitable directory. | |
354 | // | |
355 | #define RETRO_ENVIRONMENT_SET_PIXEL_FORMAT 10 | |
356 | // const enum retro_pixel_format * -- | |
357 | // Sets the internal pixel format used by the implementation. | |
c19aba43 TK |
358 | // The default pixel format is RETRO_PIXEL_FORMAT_0RGB1555. |
359 | // This pixel format however, is deprecated (see enum retro_pixel_format). | |
38c2028e | 360 | // If the call returns false, the frontend does not support this pixel format. |
361 | // This function should be called inside retro_load_game() or retro_get_system_av_info(). | |
c19aba43 TK |
362 | // |
363 | #define RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS 11 | |
364 | // const struct retro_input_descriptor * -- | |
365 | // Sets an array of retro_input_descriptors. | |
366 | // It is up to the frontend to present this in a usable way. | |
367 | // The array is terminated by retro_input_descriptor::description being set to NULL. | |
368 | // This function can be called at any time, but it is recommended to call it as early as possible. | |
369 | ||
38c2028e | 370 | |
371 | enum retro_pixel_format | |
372 | { | |
c19aba43 TK |
373 | // 0RGB1555, native endian. 0 bit must be set to 0. |
374 | // This pixel format is default for compatibility concerns only. | |
375 | // If a 15/16-bit pixel format is desired, consider using RGB565. | |
376 | RETRO_PIXEL_FORMAT_0RGB1555 = 0, | |
377 | ||
378 | // XRGB8888, native endian. X bits are ignored. | |
379 | RETRO_PIXEL_FORMAT_XRGB8888 = 1, | |
380 | ||
381 | // RGB565, native endian. This pixel format is the recommended format to use if a 15/16-bit format is desired | |
382 | // as it is the pixel format that is typically available on a wide range of low-power devices. | |
383 | // It is also natively supported in APIs like OpenGL ES. | |
384 | RETRO_PIXEL_FORMAT_RGB565 = 2, | |
385 | ||
386 | // Ensure sizeof() == sizeof(int). | |
387 | RETRO_PIXEL_FORMAT_UNKNOWN = INT_MAX | |
38c2028e | 388 | }; |
389 | ||
390 | struct retro_message | |
391 | { | |
392 | const char *msg; // Message to be displayed. | |
393 | unsigned frames; // Duration in frames of message. | |
394 | }; | |
395 | ||
c19aba43 TK |
396 | // Describes how the libretro implementation maps a libretro input bind |
397 | // to its internal input system through a human readable string. | |
398 | // This string can be used to better let a user configure input. | |
399 | struct retro_input_descriptor | |
400 | { | |
401 | // Associates given parameters with a description. | |
402 | unsigned port; | |
403 | unsigned device; | |
404 | unsigned index; | |
405 | unsigned id; | |
406 | ||
407 | const char *description; // Human readable description for parameters. | |
408 | // The pointer must remain valid until retro_unload_game() is called. | |
409 | }; | |
410 | ||
38c2028e | 411 | struct retro_system_info |
412 | { | |
c19aba43 TK |
413 | // All pointers are owned by libretro implementation, and pointers must remain valid until retro_deinit() is called. |
414 | ||
38c2028e | 415 | const char *library_name; // Descriptive name of library. Should not contain any version numbers, etc. |
416 | const char *library_version; // Descriptive version of core. | |
417 | ||
418 | const char *valid_extensions; // A string listing probably rom extensions the core will be able to load, separated with pipe. | |
419 | // I.e. "bin|rom|iso". | |
420 | // Typically used for a GUI to filter out extensions. | |
421 | ||
422 | bool need_fullpath; // If true, retro_load_game() is guaranteed to provide a valid pathname in retro_game_info::path. | |
423 | // ::data and ::size are both invalid. | |
424 | // If false, ::data and ::size are guaranteed to be valid, but ::path might not be valid. | |
425 | // This is typically set to true for libretro implementations that must load from file. | |
426 | // Implementations should strive for setting this to false, as it allows the frontend to perform patching, etc. | |
427 | ||
428 | bool block_extract; // If true, the frontend is not allowed to extract any archives before loading the real ROM. | |
429 | // Necessary for certain libretro implementations that load games from zipped archives. | |
430 | }; | |
431 | ||
432 | struct retro_game_geometry | |
433 | { | |
434 | unsigned base_width; // Nominal video width of game. | |
435 | unsigned base_height; // Nominal video height of game. | |
436 | unsigned max_width; // Maximum possible width of game. | |
437 | unsigned max_height; // Maximum possible height of game. | |
438 | ||
439 | float aspect_ratio; // Nominal aspect ratio of game. If aspect_ratio is <= 0.0, | |
440 | // an aspect ratio of base_width / base_height is assumed. | |
441 | // A frontend could override this setting if desired. | |
442 | }; | |
443 | ||
444 | struct retro_system_timing | |
445 | { | |
446 | double fps; // FPS of video content. | |
447 | double sample_rate; // Sampling rate of audio. | |
448 | }; | |
449 | ||
450 | struct retro_system_av_info | |
451 | { | |
452 | struct retro_game_geometry geometry; | |
453 | struct retro_system_timing timing; | |
454 | }; | |
455 | ||
456 | struct retro_variable | |
457 | { | |
458 | const char *key; // Variable to query in RETRO_ENVIRONMENT_GET_VARIABLE. | |
459 | // If NULL, obtains the complete environment string if more complex parsing is necessary. | |
460 | // The environment string is formatted as key-value pairs delimited by semicolons as so: | |
461 | // "key1=value1;key2=value2;..." | |
462 | const char *value; // Value to be obtained. If key does not exist, it is set to NULL. | |
463 | }; | |
464 | ||
465 | struct retro_game_info | |
466 | { | |
467 | const char *path; // Path to game, UTF-8 encoded. Usually used as a reference. | |
468 | // May be NULL if rom was loaded from stdin or similar. | |
469 | // retro_system_info::need_fullpath guaranteed that this path is valid. | |
470 | const void *data; // Memory buffer of loaded game. Will be NULL if need_fullpath was set. | |
471 | size_t size; // Size of memory buffer. | |
472 | const char *meta; // String of implementation specific meta-data. | |
473 | }; | |
474 | ||
475 | // Callbacks | |
476 | // | |
477 | // Environment callback. Gives implementations a way of performing uncommon tasks. Extensible. | |
478 | typedef bool (*retro_environment_t)(unsigned cmd, void *data); | |
479 | ||
480 | // Render a frame. Pixel format is 15-bit 0RGB1555 native endian unless changed (see RETRO_ENVIRONMENT_SET_PIXEL_FORMAT). | |
481 | // Width and height specify dimensions of buffer. | |
482 | // Pitch specifices length in bytes between two lines in buffer. | |
c19aba43 TK |
483 | // For performance reasons, it is highly recommended to have a frame that is packed in memory, i.e. pitch == width * byte_per_pixel. |
484 | // Certain graphic APIs, such as OpenGL ES, do not like textures that are not packed in memory. | |
38c2028e | 485 | typedef void (*retro_video_refresh_t)(const void *data, unsigned width, unsigned height, size_t pitch); |
486 | ||
487 | // Renders a single audio frame. Should only be used if implementation generates a single sample at a time. | |
488 | // Format is signed 16-bit native endian. | |
489 | typedef void (*retro_audio_sample_t)(int16_t left, int16_t right); | |
490 | // Renders multiple audio frames in one go. One frame is defined as a sample of left and right channels, interleaved. | |
491 | // I.e. int16_t buf[4] = { l, r, l, r }; would be 2 frames. | |
492 | // Only one of the audio callbacks must ever be used. | |
493 | typedef size_t (*retro_audio_sample_batch_t)(const int16_t *data, size_t frames); | |
494 | ||
495 | // Polls input. | |
496 | typedef void (*retro_input_poll_t)(void); | |
497 | // Queries for input for player 'port'. device will be masked with RETRO_DEVICE_MASK. | |
498 | // Specialization of devices such as RETRO_DEVICE_JOYPAD_MULTITAP that have been set with retro_set_controller_port_device() | |
499 | // will still use the higher level RETRO_DEVICE_JOYPAD to request input. | |
500 | typedef int16_t (*retro_input_state_t)(unsigned port, unsigned device, unsigned index, unsigned id); | |
501 | ||
502 | // Sets callbacks. retro_set_environment() is guaranteed to be called before retro_init(). | |
503 | // The rest of the set_* functions are guaranteed to have been called before the first call to retro_run() is made. | |
504 | void retro_set_environment(retro_environment_t); | |
505 | void retro_set_video_refresh(retro_video_refresh_t); | |
506 | void retro_set_audio_sample(retro_audio_sample_t); | |
507 | void retro_set_audio_sample_batch(retro_audio_sample_batch_t); | |
508 | void retro_set_input_poll(retro_input_poll_t); | |
509 | void retro_set_input_state(retro_input_state_t); | |
510 | ||
511 | // Library global initialization/deinitialization. | |
512 | void retro_init(void); | |
513 | void retro_deinit(void); | |
514 | ||
515 | // Must return RETRO_API_VERSION. Used to validate ABI compatibility when the API is revised. | |
516 | unsigned retro_api_version(void); | |
517 | ||
518 | // Gets statically known system info. Pointers provided in *info must be statically allocated. | |
519 | // Can be called at any time, even before retro_init(). | |
520 | void retro_get_system_info(struct retro_system_info *info); | |
521 | ||
522 | // Gets information about system audio/video timings and geometry. | |
523 | // Can be called only after retro_load_game() has successfully completed. | |
c19aba43 TK |
524 | // NOTE: The implementation of this function might not initialize every variable if needed. |
525 | // E.g. geom.aspect_ratio might not be initialized if core doesn't desire a particular aspect ratio. | |
38c2028e | 526 | void retro_get_system_av_info(struct retro_system_av_info *info); |
527 | ||
528 | // Sets device to be used for player 'port'. | |
529 | void retro_set_controller_port_device(unsigned port, unsigned device); | |
530 | ||
531 | // Resets the current game. | |
532 | void retro_reset(void); | |
533 | ||
534 | // Runs the game for one video frame. | |
535 | // During retro_run(), input_poll callback must be called at least once. | |
536 | // | |
537 | // If a frame is not rendered for reasons where a game "dropped" a frame, | |
538 | // this still counts as a frame, and retro_run() should explicitly dupe a frame if GET_CAN_DUPE returns true. | |
539 | // In this case, the video callback can take a NULL argument for data. | |
540 | void retro_run(void); | |
541 | ||
542 | // Returns the amount of data the implementation requires to serialize internal state (save states). | |
543 | // 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 | |
544 | // ensure that the frontend can allocate a save state buffer once. | |
545 | size_t retro_serialize_size(void); | |
546 | ||
547 | // Serializes internal state. If failed, or size is lower than retro_serialize_size(), it should return false, true otherwise. | |
548 | bool retro_serialize(void *data, size_t size); | |
549 | bool retro_unserialize(const void *data, size_t size); | |
550 | ||
551 | void retro_cheat_reset(void); | |
552 | void retro_cheat_set(unsigned index, bool enabled, const char *code); | |
553 | ||
554 | // Loads a game. | |
555 | bool retro_load_game(const struct retro_game_info *game); | |
556 | ||
557 | // Loads a "special" kind of game. Should not be used except in extreme cases. | |
558 | bool retro_load_game_special( | |
559 | unsigned game_type, | |
560 | const struct retro_game_info *info, size_t num_info | |
561 | ); | |
562 | ||
563 | // Unloads a currently loaded game. | |
564 | void retro_unload_game(void); | |
565 | ||
566 | // Gets region of game. | |
567 | unsigned retro_get_region(void); | |
568 | ||
569 | // Gets region of memory. | |
570 | void *retro_get_memory_data(unsigned id); | |
571 | size_t retro_get_memory_size(unsigned id); | |
572 | ||
573 | #ifdef __cplusplus | |
574 | } | |
575 | #endif | |
576 | ||
577 | #endif |