1 /* Copyright (C) 2010-2015 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 1927