diff --git a/.gitignore b/.gitignore index 49eda8d..28dae95 100644 --- a/.gitignore +++ b/.gitignore @@ -3,10 +3,14 @@ /build-switch /build-vita /build-wiiu +/build-libretro /.gradle /src/android/.cxx /eboot.bin /noods +/noods*.so +/noods*.dll +/noods*.dylib /noods.aab /NooDS.app /NooDS.dmg diff --git a/Makefile b/Makefile index dbd5276..5fbfdfc 100644 --- a/Makefile +++ b/Makefile @@ -100,10 +100,14 @@ wiiu: vita: $(MAKE) -f Makefile.vita +libretro: + $(MAKE) -f Makefile.libretro + clean: if [ -d "build-android" ]; then ./gradlew clean; fi if [ -d "build-switch" ]; then $(MAKE) -f Makefile.switch clean; fi if [ -d "build-wiiu" ]; then $(MAKE) -f Makefile.wiiu clean; fi if [ -d "build-vita" ]; then $(MAKE) -f Makefile.vita clean; fi + if [ -d "build-libretro" ]; then $(MAKE) -f Makefile.libretro clean; fi rm -rf $(BUILD) rm -f $(NAME) diff --git a/Makefile.libretro b/Makefile.libretro new file mode 100644 index 0000000..1c2d5e0 --- /dev/null +++ b/Makefile.libretro @@ -0,0 +1,36 @@ +NAME := noods_libretro +BUILD := build-libretro +GIT_VERSION := "$(shell git describe --abbrev=7 --always --tags)" +SRCS := src src/common src/libretro +ARGS := -Ofast -flto -std=c++11 -D__LIBRETRO__ -DVERSION=\"$(GIT_VERSION)\" + +CPPFILES := $(foreach dir,$(SRCS),$(wildcard $(dir)/*.cpp)) +HFILES := $(foreach dir,$(SRCS),$(wildcard $(dir)/*.h)) +OFILES := $(patsubst %.cpp,$(BUILD)/%.o,$(CPPFILES)) + +ifeq ($(OS),Windows_NT) + ARGS += -static -DWINDOWS + SHARED_EXT := .dll +else + ifeq ($(shell uname -s),Darwin) + ARGS += -DMACOS + SHARED_EXT := .dylib + else + SHARED_EXT := .so + endif +endif + +all: $(NAME) + +$(NAME): $(OFILES) + g++ -shared -o $@$(SHARED_EXT) $(ARGS) $^ $(LIBS) + +$(BUILD)/%.o: %.cpp $(HFILES) $(BUILD) + g++ -c -fPIC -o $@ $(ARGS) $(INCS) $< + +$(BUILD): + for dir in $(SRCS); do mkdir -p $(BUILD)/$$dir; done + +clean: + rm -rf $(BUILD) + rm -f $(NAME)$(SHARED_EXT) diff --git a/noods_libretro.info b/noods_libretro.info new file mode 100644 index 0000000..7755074 --- /dev/null +++ b/noods_libretro.info @@ -0,0 +1,32 @@ +display_name = "Nintendo - DS (NooDS)" +authors = "Hydr8gon" +supported_extensions = "nds" +corename = "NooDS" +manufacturer = "Nintendo" +categories = "Emulator" +systemname = "Nintendo DS" +systemid = "nds" +database = "Nintendo - Nintendo DS|Nintendo - Nintendo DS (Download Play)" +license = "GPLv3" +permissions = "" +display_version = "Git" +supports_no_game = "true" +hw_render = "false" + +# Firmware / BIOS +firmware_count = 4 +firmware0_desc = "firmware.bin (NDS Firmware)" +firmware0_path = "firmware.bin" +firmware0_opt = "true" +firmware1_desc = "bios7.bin (ARM7 BIOS)" +firmware1_path = "bios7.bin" +firmware1_opt = "true" +firmware2_desc = "bios9.bin (ARM9 BIOS)" +firmware2_path = "bios9.bin" +firmware2_opt = "true" +firmware3_desc = "nds_sd_card.bin (NDS SD card)" +firmware3_path = "nds_sd_card.bin" +firmware3_opt = "true" +notes = "(!) bios7.bin (md5): df692a80a5b1bc90728bc3dfc76cd948|(!) bios9.bin (md5): a392174eb3e572fed6447e956bde4b25" + +description = "A speedy DS emulator" diff --git a/src/libretro/libretro.cpp b/src/libretro/libretro.cpp new file mode 100644 index 0000000..d9c11ab --- /dev/null +++ b/src/libretro/libretro.cpp @@ -0,0 +1,1064 @@ +#include +#include +#include +#include + +#include +#include +#include + +#include "libretro.h" + +#include "../common/screen_layout.h" +#include "../settings.h" +#include "../core.h" +#include "../defines.h" + +#ifndef VERSION +#define VERSION "0.1" +#endif + +static retro_environment_t envCallback; +static retro_video_refresh_t videoCallback; +static retro_audio_sample_batch_t audioBatchCallback; +static retro_input_poll_t inputPollCallback; +static retro_input_state_t inputStateCallback; + +static struct retro_log_callback logging; +static retro_log_printf_t logCallback; + +static retro_microphone_t* microphone; +static retro_microphone_interface micInterface; +static bool micAvailable; + +static std::string systemPath; +static std::string savesPath; + +static Core *core; +static ScreenLayout layout; +static ScreenLayout touch; + +static std::string ndsPath; +static std::string gbaPath; + +static int ndsSaveFd = -1; +static int gbaSaveFd = -1; + +static std::vector videoBuffer; +static uint32_t videoBufferSize; + +static std::string micInputMode; +static std::string micButtonMode; + +static std::string touchMode; +static std::string screenSwapMode; + +static int screenArrangement; +static int screenRotation; + +static bool gbaModeEnabled; +static bool renderGbaScreen; +static bool renderTopScreen; +static bool renderBotScreen; + +static bool micToggled; +static bool micActive; + +static bool showTouchCursor; +static bool screenSwapped; +static bool swapScreens; +static bool screenTouched; + +static int lastMouseX = 0; +static int lastMouseY = 0; + +static int touchX = 0; +static int touchY = 0; + +static int keymap[] = { + RETRO_DEVICE_ID_JOYPAD_A, + RETRO_DEVICE_ID_JOYPAD_B, + RETRO_DEVICE_ID_JOYPAD_SELECT, + RETRO_DEVICE_ID_JOYPAD_START, + RETRO_DEVICE_ID_JOYPAD_RIGHT, + RETRO_DEVICE_ID_JOYPAD_LEFT, + RETRO_DEVICE_ID_JOYPAD_UP, + RETRO_DEVICE_ID_JOYPAD_DOWN, + RETRO_DEVICE_ID_JOYPAD_R, + RETRO_DEVICE_ID_JOYPAD_L, + RETRO_DEVICE_ID_JOYPAD_X, + RETRO_DEVICE_ID_JOYPAD_Y +}; + +static int arrangeMap [] = { + 0, // 0 - Automatic 0 - Automatic + 2, // 1 - Vertical 2 - Horizontal + 1, // 2 - Horizontal 1 - Vertical + 3, // 3 - Single Screen 3 - Single Screen +}; + +static int rotationMap [] = { + 0, // 0 - Normal 0 - Normal + 2, // 1 - RotatedLeft 2 - Counter-clockwise + 0, // 2 - UpsideDown 0 - Normal + 1, // 3 - RotatedRight 1 - Clockwise +}; + +static int32_t clampValue(int32_t value, int32_t min, int32_t max) +{ + return std::max(min, std::min(max, value)); +} + +static std::string normalizePath(std::string path, bool addSlash = false) +{ + std::string newPath = path; + if (addSlash && newPath.back() != '/') newPath += '/'; +#ifdef WINDOWS + std::replace(newPath.begin(), newPath.end(), '\\', '/'); +#endif + return newPath; +} + +static std::string getNameFromPath(std::string path) +{ + std::string base = path.substr(path.find_last_of("/\\") + 1); + return base.substr(0, base.rfind(".")); +} + +static void swapScreenPositions(ScreenLayout& sl) +{ + std::swap(sl.topWidth, sl.botWidth); + std::swap(sl.topHeight, sl.botHeight); + std::swap(sl.topX, sl.botX); + std::swap(sl.topY, sl.botY); +} + +static void logFallback(enum retro_log_level level, const char *fmt, ...) +{ + (void)level; + va_list va; + va_start(va, fmt); + vfprintf(stderr, fmt, va); + va_end(va); +} + +static std::string fetchVariable(std::string key, std::string def) +{ + struct retro_variable var = { nullptr }; + var.key = key.c_str(); + + if (!envCallback(RETRO_ENVIRONMENT_GET_VARIABLE, &var) || var.value == nullptr) + { + logCallback(RETRO_LOG_WARN, "Fetching variable %s failed.", var.key); + return def; + } + + return std::string(var.value); +} + +static bool fetchVariableBool(std::string key, bool def) +{ + return fetchVariable(key, def ? "enabled" : "disabled") == "enabled"; +} + +static int fetchVariableEnum(std::string key, std::vector list, int def = 0) +{ + auto val = fetchVariable(key, list[def]); + auto itr = std::find(list.begin(), list.end(), val); + + return std::distance(list.begin(), itr); +} + +static std::string getSaveDir() +{ + char* dir = nullptr; + if (!envCallback(RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY, &dir) || dir == nullptr) + { + logCallback(RETRO_LOG_INFO, "No save directory provided by LibRetro."); + return std::string("NooDS"); + } + return std::string(dir); +} + +static std::string getSystemDir() +{ + char* dir = nullptr; + if (!envCallback(RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY, &dir) || dir == nullptr) + { + logCallback(RETRO_LOG_INFO, "No system directory provided by LibRetro."); + return std::string("NooDS"); + } + return std::string(dir); +} + +static bool getButtonState(unsigned id) +{ + return inputStateCallback(0, RETRO_DEVICE_JOYPAD, 0, id); +} + +static float getAxisState(unsigned index, unsigned id) +{ + return inputStateCallback(0, RETRO_DEVICE_ANALOG, index, id); +} + +static void initInput(void) +{ + static const struct retro_controller_description controllers[] = { + { "Nintendo DS", RETRO_DEVICE_JOYPAD }, + { NULL, 0 }, + }; + + static const struct retro_controller_info ports[] = { + { controllers, 1 }, + { NULL, 0 }, + }; + + envCallback(RETRO_ENVIRONMENT_SET_CONTROLLER_INFO, (void*)ports); + + struct retro_input_descriptor desc[] = { + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_LEFT, "Left" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_UP, "Up" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_DOWN, "Down" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_RIGHT, "Right" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_A, "A" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_B, "B" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_SELECT, "Select" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_START, "Start" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_R, "R" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_L, "L" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_X, "X" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_Y, "Y" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_L2, "Microphone" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_R2, "Swap screens" }, + { 0, RETRO_DEVICE_JOYPAD, 0, RETRO_DEVICE_ID_JOYPAD_R3, "Touch joystick" }, + { 0, RETRO_DEVICE_ANALOG, RETRO_DEVICE_INDEX_ANALOG_RIGHT, RETRO_DEVICE_ID_ANALOG_X, "Touch joystick X" }, + { 0, RETRO_DEVICE_ANALOG, RETRO_DEVICE_INDEX_ANALOG_RIGHT, RETRO_DEVICE_ID_ANALOG_Y, "Touch joystick Y" }, + { 0 }, + }; + + envCallback(RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS, &desc); +} + +static void initConfig() +{ + static const retro_variable values[] = { + { "noods_directBoot", "Direct Boot; enabled|disabled" }, + { "noods_fpsLimiter", "FPS Limiter; disabled|enabled" }, + { "noods_romInRam", "Keep ROM in RAM; disabled|enabled" }, + { "noods_threaded2D", "Threaded 2D; enabled|disabled" }, + { "noods_threaded3D", "Threaded 3D; 1 Thread|2 Threads|3 Threads|4 Threads|Disabled" }, + { "noods_highRes3D", "High Resolution 3D; disabled|enabled" }, + { "noods_screenArrangement", "Screen Arrangement; Automatic|Vertical|Horizontal|Single Screen" }, + { "noods_screenRotation", "Screen Rotation; Normal|Rotated Left|Rotated Right" }, + { "noods_screenSizing", "Screen Sizing; Even|Enlarge Top|Enlarge Bottom" }, + { "noods_screenPosition", "Screen Position; Center|Top|Bottom|Left|Right" }, + { "noods_screenGap", "Screen Gap; None|Quarter|Half|Full" }, + { "noods_gbaCrop", "Crop GBA Screen; enabled|disabled" }, + { "noods_screenFilter", "Screen Filter; Nearest|Upscaled|Linear" }, + { "noods_screenGhost", "Simulate Ghosting; disabled|enabled" }, + { "noods_swapScreenMode", "Swap Screen Mode; Toggle|Hold" }, + { "noods_touchMode", "Touch Mode; Auto|Pointer|Joystick|None" }, + { "noods_touchCursor", "Show Touch Cursor; enabled|disabled" }, + { "noods_micInputMode", "Microphone Input Mode; Silence|Noise|Microphone" }, + { "noods_micButtonMode", "Microphone Button Mode; Toggle|Hold|Always" }, + { nullptr, nullptr } + }; + + envCallback(RETRO_ENVIRONMENT_SET_VARIABLES, (void*)values); +} + +static void updateConfig() +{ + Settings::basePath = savesPath + "noods"; + Settings::bios9Path = systemPath + "bios9.bin"; + Settings::bios7Path = systemPath + "bios7.bin"; + Settings::firmwarePath = systemPath + "firmware.bin"; + Settings::sdImagePath = systemPath + "nds_sd_card.bin"; + + Settings::directBoot = fetchVariableBool("noods_directBoot", true); + Settings::fpsLimiter = fetchVariableBool("noods_fpsLimiter", false); + Settings::romInRam = fetchVariableBool("noods_romInRam", false); + Settings::threaded2D = fetchVariableBool("noods_threaded2D", true); + Settings::threaded3D = fetchVariableEnum("noods_threaded3D", {"Disabled", "1 Thread", "2 Threads", "3 Threads", "4 Threads"}, 1); + Settings::highRes3D = fetchVariableBool("noods_highRes3D", false); + Settings::screenFilter = fetchVariableEnum("noods_screenFilter", {"Nearest", "Upscaled", "Linear"}); + Settings::screenGhost = fetchVariableBool("noods_screenGhost", false); + + micInputMode = fetchVariable("noods_micInputMode", "Silence"); + micButtonMode = fetchVariable("noods_micButtonMode", "Toggle"); + + screenArrangement = fetchVariableEnum("noods_screenArrangement", {"Automatic", "Vertical", "Horizontal", "Single Screen"}); + screenRotation = fetchVariableEnum("noods_screenRotation", {"Normal", "Rotated Left", "Upside Down", "Rotated Right"}); + screenSwapMode = fetchVariable("noods_swapScreenMode", "Toggle"); + touchMode = fetchVariable("noods_touchMode", "Touch"); + showTouchCursor = fetchVariableBool("noods_touchCursor", true); + + ScreenLayout::gbaCrop = fetchVariableBool("noods_gbaCrop", true); + ScreenLayout::screenSizing = fetchVariableEnum("noods_screenSizing", {"Even", "Enlarge Top", "Enlarge Bottom"}); + ScreenLayout::screenPosition = fetchVariableEnum("noods_screenPosition", {"Center", "Top", "Bottom", "Left", "Right"}); + ScreenLayout::screenGap = fetchVariableEnum("noods_screenGap", {"None", "Quarter", "Half", "Full"}); + + int screenSizing = 0; int screenWidth = 0; int screenHeight = 0; + + if (screenArrangement == 1 && screenRotation && ScreenLayout::screenSizing) + { + screenSizing = ScreenLayout::screenSizing; + ScreenLayout::screenSizing = screenSizing == 2 ? 1 : 2; + } + + ScreenLayout::screenArrangement = screenRotation ? arrangeMap[screenArrangement] : screenArrangement; + ScreenLayout::screenRotation = rotationMap[0]; + layout.update(0, 0, gbaModeEnabled, false); + + if (ScreenLayout::screenSizing && ScreenLayout::screenArrangement == 2) + { + screenWidth = layout.minWidth / 2 * 3; + screenHeight = layout.minHeight * 2; + } + + if (ScreenLayout::screenSizing && ScreenLayout::screenArrangement < 2) + { + screenWidth = layout.minWidth * 2; + screenHeight = layout.minHeight / 2 * 3; + } + + if (screenWidth && screenHeight) + { + ScreenLayout::integerScale = true; + layout.update(screenWidth, screenHeight, gbaModeEnabled, false); + + layout.minWidth = layout.winWidth; + layout.minHeight = layout.winHeight; + } + + if (screenArrangement == 1 && screenRotation) + { + ScreenLayout::screenSizing = screenSizing; + swapScreenPositions(layout); + } + + ScreenLayout::screenArrangement = screenArrangement; + ScreenLayout::screenRotation = rotationMap[screenRotation]; + touch.update(0, 0, gbaModeEnabled, false); + + if (screenWidth && screenHeight) + { + if (ScreenLayout::screenRotation) std::swap(screenWidth, screenHeight); + touch.update(screenWidth, screenHeight, gbaModeEnabled, false); + + touch.minWidth = touch.winWidth; + touch.minHeight = touch.winHeight; + } + + bool shift = Settings::highRes3D || Settings::screenFilter == 1; + auto bsize = (layout.minWidth << shift) * (layout.minHeight << shift); + + if (videoBufferSize != bsize) + { + videoBuffer.resize(bsize); + videoBufferSize = bsize; + } + + memset(videoBuffer.data(), 0, videoBuffer.size() * sizeof(videoBuffer[0])); + + envCallback(RETRO_ENVIRONMENT_SET_ROTATION, &screenRotation); +} + +static void checkConfigVariables() +{ + bool updated = false; + envCallback(RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE, &updated); + + if (core && gbaModeEnabled != core->gbaMode) + { + gbaModeEnabled = core->gbaMode; + updated = true; + } + + if (updated) + { + updateConfig(); + + retro_system_av_info info; + retro_get_system_av_info(&info); + envCallback(RETRO_ENVIRONMENT_SET_GEOMETRY, &info); + } +} + +static void updateScreenState() +{ + bool singleScreen = ScreenLayout::screenArrangement == 3; + auto screenSizing = ScreenLayout::screenSizing; + + if (screenSizing <= 1 && swapScreens) + screenSizing = 2; + else if (screenSizing == 2 && swapScreens) + screenSizing = 1; + + renderGbaScreen = gbaModeEnabled && ScreenLayout::gbaCrop; + renderTopScreen = !renderGbaScreen && (!singleScreen || screenSizing <= 1); + renderBotScreen = !renderGbaScreen && (!singleScreen || screenSizing == 2); +} + +static void drawCursor(uint32_t *data, int32_t pointX, int32_t pointY, int32_t size = 2) +{ + bool shift = Settings::highRes3D || Settings::screenFilter == 1; + auto scale = layout.botWidth / 256; + + uint32_t posX = clampValue(pointX, size, (layout.botWidth / scale) - size); + uint32_t posY = clampValue(pointY, size, (layout.botHeight / scale) - size); + + uint32_t minX = layout.botX << shift; + uint32_t maxX = layout.minWidth << shift; + + uint32_t minY = layout.botY << shift; + uint32_t maxY = layout.minHeight << shift; + + uint32_t curX = (layout.botX + (posX * scale)) << shift; + uint32_t curY = (layout.botY + (posY * scale)) << shift; + + uint32_t cursorSize = (size * scale) << shift; + + uint32_t startY = clampValue(curY - cursorSize, minY, maxY); + uint32_t endY = clampValue(curY + cursorSize, minY, maxY); + + uint32_t startX = clampValue(curX - cursorSize, minX, maxX); + uint32_t endX = clampValue(curX + cursorSize, minX, maxX); + + for (uint32_t y = startY; y < endY; y++) + { + for (uint32_t x = startX; x < endX; x++) + { + uint32_t& pixel = data[(y * maxX) + x]; + pixel = (0xFFFFFF - pixel) | 0xFF000000; + } + } +} + +static void copyScreen(uint32_t *src, uint32_t *dst, int sw, int sh, int dx, int dy, int dw, int dh, int stride) +{ + int scaleX = dw / sw; + int scaleY = dh / sh; + + for (int y = 0; y < dh; ++y) + { + int srcY = (y / scaleY) * sw; + int dstY = (dy + y) * stride + dx; + + for (int x = 0; x < dw; ++x) + { + uint32_t pixel = src[srcY + (x / scaleX)]; + + dst[dstY + x] = + ((pixel & 0xFF000000)) | + ((pixel & 0x00FF0000) >> 16) | + ((pixel & 0x0000FF00)) | + ((pixel & 0x000000FF) << 16); + } + } +} + +static void drawTexture(uint32_t *buffer) +{ + bool shift = Settings::highRes3D || Settings::screenFilter == 1; + auto width = layout.minWidth << shift; + auto height = layout.minHeight << shift; + + if (renderGbaScreen) + { + copyScreen( + &buffer[0], videoBuffer.data(), + 240 << shift, 160 << shift, + layout.topX << shift, layout.topY << shift, + layout.topWidth << shift, layout.topHeight << shift, + width + ); + } + + if (renderTopScreen) + { + copyScreen( + &buffer[0], videoBuffer.data(), + 256 << shift, 192 << shift, + layout.topX << shift, layout.topY << shift, + layout.topWidth << shift, layout.topHeight << shift, + width + ); + } + + if (renderBotScreen) + { + copyScreen( + &buffer[(256 * 192) << (shift * 2)], videoBuffer.data(), + 256 << shift, 192 << shift, + layout.botX << shift, layout.botY << shift, + layout.botWidth << shift, layout.botHeight << shift, + width + ); + + if (showTouchCursor) + drawCursor(videoBuffer.data(), touchX, touchY); + } + + videoCallback(videoBuffer.data(), width, height, width * 4); +} + +static void playbackAudio() +{ + static int16_t buffer[547 * 2]; + uint32_t *original = core->spu.getSamples(547); + + for (int i = 0; i < 547; i++) + { + buffer[i * 2 + 0] = original[i] >> 0; + buffer[i * 2 + 1] = original[i] >> 16; + } + delete[] original; + + uint32_t size = sizeof(buffer) / (2 * sizeof(int16_t)); + audioBatchCallback(buffer, size); +} + +static void openMicrophone() +{ + if (micAvailable && !microphone) + { + retro_microphone_params_t params = { 44100 }; + microphone = micInterface.open_mic(¶ms); + + micInterface.set_mic_state(microphone, false); + } +} + +static void closeMicrophone() +{ + if (micAvailable && microphone) + { + micInterface.close_mic(microphone); + microphone = nullptr; + } +} + +static void setMicrophoneState(bool enabled) +{ + if (micInputMode == "Microphone" && micAvailable && microphone) + micInterface.set_mic_state(microphone, enabled); +} + +static void sendMicSamples() +{ + static const size_t maxSamples = 735; + static int16_t buffer[maxSamples]; + + size_t samplesRead = 0; + + if (micInputMode == "Microphone" && microphone && micInterface.get_mic_state(microphone)) + { + samplesRead = micInterface.read_mic(microphone, buffer, maxSamples); + } + else if (micInputMode == "Noise") + { + samplesRead = maxSamples; + for (int i = 0; i < maxSamples; i++) buffer[i] = rand() & 0xFFFF; + } + else + { + samplesRead = 0; + memset(buffer, 0, sizeof(buffer)); + } + + if (samplesRead) + core->spi.sendMicData(buffer, samplesRead, 44100); +} + +static int getSaveFileDesc(std::string path) +{ + int fd = open(path.c_str(), O_RDWR); + if (fd == -1) + { + std::ofstream file(path, std::ios::binary); + if (file.is_open()) + { + file.put(0xFF); + file.close(); + } + fd = open(path.c_str(), O_RDWR); + } + return fd; +} + +static void closeSaveFileDesc() +{ + close(ndsSaveFd); + ndsSaveFd = -1; + + close(gbaSaveFd); + gbaSaveFd = -1; +} + +static bool createCore(std::string ndsRom = "", std::string gbaRom = "") +{ + try + { + if (core) delete core; + + closeSaveFileDesc(); + + if (ndsRom != "") + ndsSaveFd = getSaveFileDesc(savesPath + getNameFromPath(ndsRom) + ".sav"); + + if (gbaRom != "") + gbaSaveFd = getSaveFileDesc(savesPath + getNameFromPath(gbaRom) + ".sav"); + + core = new Core(ndsRom, gbaRom, 0, -1, -1, ndsSaveFd, gbaSaveFd); + return true; + } + catch (CoreError e) + { + closeSaveFileDesc(); + + switch (e) + { + case ERROR_BIOS: + logCallback(RETRO_LOG_INFO, "Error Loading BIOS"); + break; + case ERROR_FIRM: + logCallback(RETRO_LOG_INFO, "Error Loading Firmware"); + break; + case ERROR_ROM: + logCallback(RETRO_LOG_INFO, "Error Loading ROM"); + break; + } + + core = nullptr; + return false; + } +} + +void retro_get_system_info(retro_system_info* info) +{ + info->need_fullpath = true; + info->valid_extensions = "nds"; + info->library_version = VERSION; + info->library_name = "NooDS"; + info->block_extract = true; +} + +void retro_get_system_av_info(retro_system_av_info* info) +{ + info->geometry.base_width = layout.minWidth; + info->geometry.base_height = layout.minHeight; + + info->geometry.max_width = info->geometry.base_width; + info->geometry.max_height = info->geometry.base_height; + info->geometry.aspect_ratio = (float)touch.minWidth / (float)touch.minHeight; + + info->timing.fps = 32.0f * 1024.0f * 1024.0f / 560190.0f; + info->timing.sample_rate = 32.0f * 1024.0f; +} + +void retro_set_environment(retro_environment_t cb) +{ + const struct retro_system_content_info_override contentOverrides[] = { + { "nds|gba", true, false }, + {} + }; + + cb(RETRO_ENVIRONMENT_SET_CONTENT_INFO_OVERRIDE, (void*)contentOverrides); + + static const struct retro_subsystem_memory_info ndsMemory[] = { + { "sav", RETRO_MEMORY_SAVE_RAM }, + }; + + static const struct retro_subsystem_rom_info dualSlot[] = { + { "Nintendo DS (Slot 1)", "nds", true, false, true, ndsMemory, 1 }, + { "GBA (Slot 2)", "gba", true, false, true, nullptr, 0 }, + }; + + static const struct retro_subsystem_rom_info gbaSlot[] = { + { "GBA (Slot 2)", "gba", true, false, true, ndsMemory, 1 }, + }; + + const struct retro_subsystem_info subsystems[] = { + { "Slot 1 & 2 Boot", "nds", dualSlot, 2, 1 }, + { "Slot 2 Boot", "gba", gbaSlot, 1, 2 }, + {} + }; + + cb(RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO, (void*)subsystems); + + bool nogameSupport = true; + cb(RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME, &nogameSupport); + + envCallback = cb; +} + +void retro_set_video_refresh(retro_video_refresh_t cb) +{ + videoCallback = cb; +} + +void retro_set_audio_sample_batch(retro_audio_sample_batch_t cb) +{ + audioBatchCallback = cb; +} + +void retro_set_audio_sample(retro_audio_sample_t cb) +{ +} + +void retro_set_input_poll(retro_input_poll_t cb) +{ + inputPollCallback = cb; +} + +void retro_set_input_state(retro_input_state_t cb) +{ + inputStateCallback = cb; +} + +void retro_init(void) +{ + enum retro_pixel_format xrgb888 = RETRO_PIXEL_FORMAT_XRGB8888; + envCallback(RETRO_ENVIRONMENT_SET_PIXEL_FORMAT, &xrgb888); + + micInterface.interface_version = RETRO_MICROPHONE_INTERFACE_VERSION; + micAvailable = envCallback(RETRO_ENVIRONMENT_GET_MICROPHONE_INTERFACE, &micInterface); + + if (envCallback(RETRO_ENVIRONMENT_GET_LOG_INTERFACE, &logging)) + logCallback = logging.log; + else + logCallback = logFallback; + + systemPath = normalizePath(getSystemDir(), true); + savesPath = normalizePath(getSaveDir(), true); +} + +void retro_deinit(void) +{ + logCallback = nullptr; +} + +bool retro_load_game_special(unsigned type, const struct retro_game_info* info, size_t info_size) +{ + ndsPath = ""; + gbaPath = ""; + + for (size_t i = 0; i < info_size; i++) + { + std::string path = normalizePath(info[i].path); + + if (path.find(".nds", path.length() - 4) != std::string::npos) + ndsPath = path; + else if (path.find(".gba", path.length() - 4) != std::string::npos) + gbaPath = path; + } + + initConfig(); + initInput(); + + if (fetchVariableBool("noods_directBoot", true) && type == 2) + gbaModeEnabled = true; + else + gbaModeEnabled = false; + + updateConfig(); + updateScreenState(); + openMicrophone(); + + if (createCore(ndsPath, gbaPath)) + { + core->cartridgeNds.writeSave(); + core->cartridgeGba.writeSave(); + + return true; + } + + return false; +} + +bool retro_load_game(const struct retro_game_info* info) +{ + size_t info_size = info ? 1 : 0; + return retro_load_game_special(0, info, info_size); +} + +void retro_unload_game(void) +{ + if (core) + { + core->cartridgeNds.writeSave(); + core->cartridgeGba.writeSave(); + + delete core; + } + + closeMicrophone(); + closeSaveFileDesc(); +} + +void retro_reset(void) +{ + createCore(ndsPath, gbaPath); +} + +void retro_run(void) +{ + checkConfigVariables(); + updateScreenState(); + inputPollCallback(); + + for (int i = 0; i < sizeof(keymap) / sizeof(*keymap); ++i) + { + if (getButtonState(keymap[i])) + core->input.pressKey(i); + else + core->input.releaseKey(i); + } + + if (micInputMode != "Silence") + { + bool micPressed = getButtonState(RETRO_DEVICE_ID_JOYPAD_L2); + bool prevStatus = micActive; + + if (micToggled != micPressed) + { + if (micButtonMode == "Toggle" && micPressed) + micActive = !micActive; + + if (micButtonMode == "Hold") + micActive = micPressed; + + micToggled = micPressed; + } + + if (micButtonMode == "Always") + micActive = true; + + if (prevStatus != micActive) setMicrophoneState(micActive); + if (micActive) sendMicSamples(); + } + + if (!renderGbaScreen) + { + bool swapPressed = getButtonState(RETRO_DEVICE_ID_JOYPAD_R2); + + if (screenSwapped != swapPressed) + { + bool needSwap = ScreenLayout::screenArrangement != 3; + bool prevSwap = swapScreens; + + if (screenSwapMode == "Toggle" && swapPressed) + swapScreens = !swapScreens; + + if (screenSwapMode == "Hold") + swapScreens = swapPressed; + + if (needSwap && prevSwap != swapScreens) + { + swapScreenPositions(layout); + swapScreenPositions(touch); + } + + screenSwapped = swapPressed; + updateScreenState(); + } + } + + if (renderBotScreen) + { + bool touchScreen = false; + auto pointerX = touchX; + auto pointerY = touchY; + + if (touchMode == "Pointer" || touchMode == "Auto") + { + auto posX = inputStateCallback(0, RETRO_DEVICE_POINTER, 0, RETRO_DEVICE_ID_POINTER_X); + auto posY = inputStateCallback(0, RETRO_DEVICE_POINTER, 0, RETRO_DEVICE_ID_POINTER_Y); + + auto newX = static_cast((posX + 0x7fff) / (float)(0x7fff * 2) * touch.minWidth); + auto newY = static_cast((posY + 0x7fff) / (float)(0x7fff * 2) * touch.minHeight); + + bool inScreenX = newX >= touch.botX && newX <= touch.botX + touch.botWidth; + bool inScreenY = newY >= touch.botY && newY <= touch.botY + touch.botHeight; + + if (inScreenX && inScreenY) + { + touchScreen |= inputStateCallback(0, RETRO_DEVICE_MOUSE, 0, RETRO_DEVICE_ID_MOUSE_LEFT); + touchScreen |= inputStateCallback(0, RETRO_DEVICE_POINTER, 0, RETRO_DEVICE_ID_POINTER_PRESSED); + } + + if ((posX != 0 || posY != 0) && (lastMouseX != newX || lastMouseY != newY)) + { + lastMouseX = newX; + lastMouseY = newY; + + pointerX = touch.getTouchX(newX, newY); + pointerY = touch.getTouchY(newX, newY); + } + } + + if (touchMode == "Joystick" || touchMode == "Auto") + { + auto speedX = (touch.botWidth / 40.0); + auto speedY = (touch.botHeight / 40.0); + + float moveX = getAxisState(RETRO_DEVICE_INDEX_ANALOG_RIGHT, RETRO_DEVICE_ID_ANALOG_X); + float moveY = getAxisState(RETRO_DEVICE_INDEX_ANALOG_RIGHT, RETRO_DEVICE_ID_ANALOG_Y); + + touchScreen |= getButtonState(RETRO_DEVICE_ID_JOYPAD_R3); + + if (screenRotation) + { + std::swap(moveX, moveY); + if (screenRotation == 1) moveX = -moveX; + if (screenRotation == 3) moveY = -moveY; + } + + if (moveX != 0 || moveY != 0) + { + pointerX = touchX + static_cast((moveX / 32767) * speedX); + pointerY = touchY + static_cast((moveY / 32767) * speedY); + } + } + + touchX = clampValue(pointerX, 0, layout.botWidth); + touchY = clampValue(pointerY, 0, layout.botHeight); + + if (touchScreen) + { + core->input.pressScreen(); + core->spi.setTouch(touchX, touchY); + screenTouched = true; + } + else if (screenTouched) + { + core->input.releaseScreen(); + core->spi.clearTouch(); + screenTouched = false; + } + } + + core->runFrame(); + + static uint32_t framebuffer[256 * 192 * 8]; + core->gpu.getFrame(framebuffer, renderGbaScreen); + + drawTexture(framebuffer); + playbackAudio(); +} + +void retro_set_controller_port_device(unsigned port, unsigned device) +{ +} + +size_t retro_serialize_size(void) +{ + FILE* tmpFile = tmpfile(); + + int fd = fileno(tmpFile); + core->saveStates.setFd(fd, false); + + core->saveStates.checkState(); + core->saveStates.saveState(); + + fflush(tmpFile); + fseek(tmpFile, 0, SEEK_END); + size_t size = ftell(tmpFile); + + fclose(tmpFile); + close(fd); + + return size; +} + +bool retro_serialize(void* data, size_t size) +{ + FILE* tmpFile = tmpfile(); + + int fd = fileno(tmpFile); + core->saveStates.setFd(fd, false); + + core->saveStates.checkState(); + core->saveStates.saveState(); + + fflush(tmpFile); + fseek(tmpFile, 0, SEEK_SET); + fread(data, 1, size, tmpFile); + + fclose(tmpFile); + close(fd); + + return true; +} + +bool retro_unserialize(const void* data, size_t size) +{ + FILE* tmpFile = tmpfile(); + + fwrite(data, 1, size, tmpFile); + fflush(tmpFile); + + int fd = fileno(tmpFile); + core->saveStates.setFd(fd, false); + + core->saveStates.checkState(); + core->saveStates.loadState(); + + fclose(tmpFile); + close(fd); + + return true; +} + +unsigned retro_get_region(void) +{ + return RETRO_REGION_NTSC; +} + +unsigned retro_api_version() +{ + return RETRO_API_VERSION; +} + +size_t retro_get_memory_size(unsigned id) +{ + if (id == RETRO_MEMORY_SYSTEM_RAM) + { + return 0x400000; + } + return 0; +} + +void* retro_get_memory_data(unsigned id) +{ + if (id == RETRO_MEMORY_SYSTEM_RAM) + { + return 0; + } + return NULL; +} + +void retro_cheat_set(unsigned index, bool enabled, const char* code) +{ + ARCheat cheat; + + cheat.name = index; + cheat.enabled = enabled; + + std::istringstream stream(code); + std::string line; + + while (getline(stream, line) && !line.empty()) + { + cheat.code.push_back(strtoll(&line[0], nullptr, 16)); + cheat.code.push_back(strtoll(&line[8], nullptr, 16)); + } + + core->actionReplay.cheats.push_back(cheat); +} + +void retro_cheat_reset(void) +{ + core->actionReplay.cheats.clear(); +} diff --git a/src/libretro/libretro.h b/src/libretro/libretro.h new file mode 100644 index 0000000..7e7b950 --- /dev/null +++ b/src/libretro/libretro.h @@ -0,0 +1,7815 @@ +/*! + * libretro.h is a simple API that allows for the creation of games and emulators. + * + * @file libretro.h + * @version 1 + * @author libretro + * @copyright Copyright (C) 2010-2023 The RetroArch team + * + * @paragraph LICENSE + * The following license statement only applies to this libretro API header (libretro.h). + * + * Copyright (C) 2010-2023 The RetroArch team + * + * Permission is hereby granted, free of charge, + * to any person obtaining a copy of this software and associated documentation files (the "Software"), + * to deal in the Software without restriction, including without limitation the rights to + * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, + * and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, + * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + */ + +#ifndef LIBRETRO_H__ +#define LIBRETRO_H__ + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +#ifndef __cplusplus +#if defined(_MSC_VER) && _MSC_VER < 1800 && !defined(SN_TARGET_PS3) +/* Hack applied for MSVC when compiling in C89 mode + * as it isn't C99-compliant. */ +#define bool unsigned char +#define true 1 +#define false 0 +#else +#include +#endif +#endif + +#ifndef RETRO_CALLCONV +# if defined(__GNUC__) && defined(__i386__) && !defined(__x86_64__) +# define RETRO_CALLCONV __attribute__((cdecl)) +# elif defined(_MSC_VER) && defined(_M_X86) && !defined(_M_X64) +# define RETRO_CALLCONV __cdecl +# else +# define RETRO_CALLCONV /* all other platforms only have one calling convention each */ +# endif +#endif + +#ifndef RETRO_API +# if defined(_WIN32) || defined(__CYGWIN__) || defined(__MINGW32__) +# ifdef RETRO_IMPORT_SYMBOLS +# ifdef __GNUC__ +# define RETRO_API RETRO_CALLCONV __attribute__((__dllimport__)) +# else +# define RETRO_API RETRO_CALLCONV __declspec(dllimport) +# endif +# else +# ifdef __GNUC__ +# define RETRO_API RETRO_CALLCONV __attribute__((__dllexport__)) +# else +# define RETRO_API RETRO_CALLCONV __declspec(dllexport) +# endif +# endif +# else +# if defined(__GNUC__) && __GNUC__ >= 4 +# define RETRO_API RETRO_CALLCONV __attribute__((__visibility__("default"))) +# else +# define RETRO_API RETRO_CALLCONV +# endif +# endif +#endif + +/** + * The major version of the libretro API and ABI. + * Cores may support multiple versions, + * or they may reject cores with unsupported versions. + * It is only incremented for incompatible API/ABI changes; + * this generally implies a function was removed or changed, + * or that a \c struct had fields removed or changed. + * @note A design goal of libretro is to avoid having to increase this value at all costs. + * This is why there are APIs that are "extended" or "V2". + */ +#define RETRO_API_VERSION 1 + +/** + * @defgroup RETRO_DEVICE Input Devices + * @brief Libretro's fundamental device abstractions. + * + * Libretro's input system consists of abstractions over standard device types, + * such as a joypad (with or without analog), mouse, keyboard, light gun, or an abstract pointer. + * Instead of managing input devices themselves, + * cores need only to map their own concept of a controller to libretro's abstractions. + * This makes it possible for frontends to map the abstract types to a real input device + * without having to worry about the correct use of arbitrary (real) controller layouts. + * @{ + */ + +#define RETRO_DEVICE_TYPE_SHIFT 8 +#define RETRO_DEVICE_MASK ((1 << RETRO_DEVICE_TYPE_SHIFT) - 1) + +/** + * Defines an ID for a subclass of a known device type. + * + * To define a subclass ID, use this macro like so: + * @code{c} + * #define RETRO_DEVICE_SUPER_SCOPE RETRO_DEVICE_SUBCLASS(RETRO_DEVICE_LIGHTGUN, 1) + * #define RETRO_DEVICE_JUSTIFIER RETRO_DEVICE_SUBCLASS(RETRO_DEVICE_LIGHTGUN, 2) + * @endcode + * + * Correct use of this macro allows a frontend to select a suitable physical device + * to map to the emulated device. + * + * @note Cores must use the base ID when polling for input, + * and frontends must only accept the base ID for this purpose. + * Polling for input using subclass IDs is reserved for future definition. + * + * @param base One of the \ref RETRO_DEVICE "base device types". + * @param id A unique ID, with respect to \c base. + * Must be a non-negative integer. + * @return A unique subclass ID. + * @see retro_controller_description + * @see retro_set_controller_port_device + */ +#define RETRO_DEVICE_SUBCLASS(base, id) (((id + 1) << RETRO_DEVICE_TYPE_SHIFT) | base) + +/** + * @defgroup RETRO_DEVICE Input Device Classes + * @{ + */ + +/** + * Indicates no input. + * + * When provided as the \c device argument to \c retro_input_state_t, + * all other arguments are ignored and zero is returned. + * + * @see retro_input_state_t + */ +#define RETRO_DEVICE_NONE 0 + +/** + * An abstraction around a game controller, known as a "RetroPad". + * + * The RetroPad is modelled after a SNES controller, + * but with additional L2/R2/L3/R3 buttons + * (similar to a PlayStation controller). + * + * When provided as the \c device argument to \c retro_input_state_t, + * the \c id argument denotes the button (including D-Pad directions) to query. + * The result of said query will be 1 if the button is down, 0 if not. + * + * There is one exception; if \c RETRO_DEVICE_ID_JOYPAD_MASK is queried + * (and the frontend supports this query), + * the result will be a bitmask of all pressed buttons. + * + * @see retro_input_state_t + * @see RETRO_DEVICE_ANALOG + * @see RETRO_DEVICE_ID_JOYPAD + * @see RETRO_DEVICE_ID_JOYPAD_MASK + * @see RETRO_ENVIRONMENT_GET_INPUT_BITMASKS + */ +#define RETRO_DEVICE_JOYPAD 1 + +/** + * An abstraction around a mouse, similar to the SNES Mouse but with more buttons. + * + * When provided as the \c device argument to \c retro_input_state_t, + * the \c id argument denotes the button or axis to query. + * For buttons, the result of said query + * will be 1 if the button is down or 0 if not. + * For mouse wheel axes, the result + * will be 1 if the wheel was rotated in that direction and 0 if not. + * For the mouse pointer axis, the result will be thee mouse's movement + * relative to the last poll. + * The core is responsible for tracking the mouse's position, + * and the frontend is responsible for preventing interference + * by the real hardware pointer (if applicable). + * + * @note This should only be used for cores that emulate mouse input, + * such as for home computers + * or consoles with mouse attachments. + * Cores that emulate light guns should use \c RETRO_DEVICE_LIGHTGUN, + * and cores that emulate touch screens should use \c RETRO_DEVICE_POINTER. + * + * @see RETRO_DEVICE_POINTER + * @see RETRO_DEVICE_LIGHTGUN + */ +#define RETRO_DEVICE_MOUSE 2 + +/** + * An abstraction around a keyboard. + * + * When provided as the \c device argument to \c retro_input_state_t, + * the \c id argument denotes the key to poll. + * + * @note This should only be used for cores that emulate keyboard input, + * such as for home computers + * or consoles with keyboard attachments. + * Cores that emulate gamepads should use \c RETRO_DEVICE_JOYPAD or \c RETRO_DEVICE_ANALOG, + * and leave keyboard compatibility to the frontend. + * + * @see RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK + * @see retro_key + */ +#define RETRO_DEVICE_KEYBOARD 3 + +/** + * An abstraction around a light gun, simular to the PlayStation's Guncon. + * + * When provided as the \c device argument to \c retro_input_state_t, + * the \c id argument denotes one of several possible inputs. + * + * The gun's coordinates are reported in screen space (similar to the pointer) + * in the range of [-0x8000, 0x7fff]. + * Zero is the center of the game's screen + * and -0x8000 represents out-of-bounds. + * The trigger and various auxiliary buttons are also reported. + * + * @note A forced off-screen shot can be requested for auto-reloading + * function in some games. + * + * @see RETRO_DEVICE_POINTER + */ +#define RETRO_DEVICE_LIGHTGUN 4 + +/** + * An extension of the RetroPad that supports analog input. + * + * The analog RetroPad provides two virtual analog sticks (similar to DualShock controllers) + * and allows any button to be treated as analog (similar to Xbox shoulder triggers). + * + * When provided as the \c device argument to \c retro_input_state_t, + * the \c id argument denotes an analog axis or an analog button. + * + * Analog axes are reported in the range of [-0x8000, 0x7fff], + * with the X axis being positive towards the right + * and the Y axis being positive towards the bottom. + * + * Analog buttons are reported in the range of [0, 0x7fff], + * where 0 is unpressed and 0x7fff is fully pressed. + * + * @note Cores should only use this type if they need analog input. + * Otherwise, \c RETRO_DEVICE_JOYPAD should be used. + * @see RETRO_DEVICE_JOYPAD + */ +#define RETRO_DEVICE_ANALOG 5 + +/** + * Input Device: Pointer. + * + * Abstracts the concept of a pointing mechanism, e.g. touch. + * This allows libretro to query in absolute coordinates where on the + * screen a mouse (or something similar) is being placed. + * For a touch centric device, coordinates reported are the coordinates + * of the press. + * + * Coordinates in X and Y are reported as: + * [-0x7fff, 0x7fff]: -0x7fff corresponds to the far left/top of the screen, + * and 0x7fff corresponds to the far right/bottom of the screen. + * The "screen" is here defined as area that is passed to the frontend and + * later displayed on the monitor. + * + * The frontend is free to scale/resize this screen as it sees fit, however, + * (X, Y) = (-0x7fff, -0x7fff) will correspond to the top-left pixel of the + * game image, etc. + * + * To check if the pointer coordinates are valid (e.g. a touch display + * actually being touched), \c RETRO_DEVICE_ID_POINTER_PRESSED returns 1 or 0. + * + * If using a mouse on a desktop, \c RETRO_DEVICE_ID_POINTER_PRESSED will + * usually correspond to the left mouse button, but this is a frontend decision. + * \c RETRO_DEVICE_ID_POINTER_PRESSED will only return 1 if the pointer is + * inside the game screen. + * + * For multi-touch, the index variable can be used to successively query + * more presses. + * If index = 0 returns true for \c _PRESSED, coordinates can be extracted + * with \c _X, \c _Y for index = 0. One can then query \c _PRESSED, \c _X, \c _Y with + * index = 1, and so on. + * Eventually \c _PRESSED will return false for an index. No further presses + * are registered at this point. + * + * @see RETRO_DEVICE_MOUSE + * @see RETRO_DEVICE_ID_POINTER_X + * @see RETRO_DEVICE_ID_POINTER_Y + * @see RETRO_DEVICE_ID_POINTER_PRESSED + */ +#define RETRO_DEVICE_POINTER 6 + +/** @} */ + +/** @defgroup RETRO_DEVICE_ID_JOYPAD RetroPad Input + * @brief Digital buttons for the RetroPad. + * + * Button placement is comparable to that of a SNES controller, + * combined with the shoulder buttons of a PlayStation controller. + * These values can also be used for the \c id field of \c RETRO_DEVICE_INDEX_ANALOG_BUTTON + * to represent analog buttons (usually shoulder triggers). + * @{ + */ + +/** The equivalent of the SNES controller's south face button. */ +#define RETRO_DEVICE_ID_JOYPAD_B 0 + +/** The equivalent of the SNES controller's west face button. */ +#define RETRO_DEVICE_ID_JOYPAD_Y 1 + +/** The equivalent of the SNES controller's left-center button. */ +#define RETRO_DEVICE_ID_JOYPAD_SELECT 2 + +/** The equivalent of the SNES controller's right-center button. */ +#define RETRO_DEVICE_ID_JOYPAD_START 3 + +/** Up on the RetroPad's D-pad. */ +#define RETRO_DEVICE_ID_JOYPAD_UP 4 + +/** Down on the RetroPad's D-pad. */ +#define RETRO_DEVICE_ID_JOYPAD_DOWN 5 + +/** Left on the RetroPad's D-pad. */ +#define RETRO_DEVICE_ID_JOYPAD_LEFT 6 + +/** Right on the RetroPad's D-pad. */ +#define RETRO_DEVICE_ID_JOYPAD_RIGHT 7 + +/** The equivalent of the SNES controller's east face button. */ +#define RETRO_DEVICE_ID_JOYPAD_A 8 + +/** The equivalent of the SNES controller's north face button. */ +#define RETRO_DEVICE_ID_JOYPAD_X 9 + +/** The equivalent of the SNES controller's left shoulder button. */ +#define RETRO_DEVICE_ID_JOYPAD_L 10 + +/** The equivalent of the SNES controller's right shoulder button. */ +#define RETRO_DEVICE_ID_JOYPAD_R 11 + +/** The equivalent of the PlayStation's rear left shoulder button. */ +#define RETRO_DEVICE_ID_JOYPAD_L2 12 + +/** The equivalent of the PlayStation's rear right shoulder button. */ +#define RETRO_DEVICE_ID_JOYPAD_R2 13 + +/** + * The equivalent of the PlayStation's left analog stick button, + * although the actual button need not be in this position. + */ +#define RETRO_DEVICE_ID_JOYPAD_L3 14 + +/** + * The equivalent of the PlayStation's right analog stick button, + * although the actual button need not be in this position. + */ +#define RETRO_DEVICE_ID_JOYPAD_R3 15 + +/** + * Represents a bitmask that describes the state of all \c RETRO_DEVICE_ID_JOYPAD button constants, + * rather than the state of a single button. + * + * @see RETRO_ENVIRONMENT_GET_INPUT_BITMASKS + * @see RETRO_DEVICE_JOYPAD + */ +#define RETRO_DEVICE_ID_JOYPAD_MASK 256 + +/** @} */ + +/** @defgroup RETRO_DEVICE_ID_ANALOG Analog RetroPad Input + * @{ + */ + +/* Index / Id values for ANALOG device. */ +#define RETRO_DEVICE_INDEX_ANALOG_LEFT 0 +#define RETRO_DEVICE_INDEX_ANALOG_RIGHT 1 +#define RETRO_DEVICE_INDEX_ANALOG_BUTTON 2 +#define RETRO_DEVICE_ID_ANALOG_X 0 +#define RETRO_DEVICE_ID_ANALOG_Y 1 + +/** @} */ + +/* Id values for MOUSE. */ +#define RETRO_DEVICE_ID_MOUSE_X 0 +#define RETRO_DEVICE_ID_MOUSE_Y 1 +#define RETRO_DEVICE_ID_MOUSE_LEFT 2 +#define RETRO_DEVICE_ID_MOUSE_RIGHT 3 +#define RETRO_DEVICE_ID_MOUSE_WHEELUP 4 +#define RETRO_DEVICE_ID_MOUSE_WHEELDOWN 5 +#define RETRO_DEVICE_ID_MOUSE_MIDDLE 6 +#define RETRO_DEVICE_ID_MOUSE_HORIZ_WHEELUP 7 +#define RETRO_DEVICE_ID_MOUSE_HORIZ_WHEELDOWN 8 +#define RETRO_DEVICE_ID_MOUSE_BUTTON_4 9 +#define RETRO_DEVICE_ID_MOUSE_BUTTON_5 10 + +/* Id values for LIGHTGUN. */ +#define RETRO_DEVICE_ID_LIGHTGUN_SCREEN_X 13 /*Absolute Position*/ +#define RETRO_DEVICE_ID_LIGHTGUN_SCREEN_Y 14 /*Absolute*/ +#define RETRO_DEVICE_ID_LIGHTGUN_IS_OFFSCREEN 15 /*Status Check*/ +#define RETRO_DEVICE_ID_LIGHTGUN_TRIGGER 2 +#define RETRO_DEVICE_ID_LIGHTGUN_RELOAD 16 /*Forced off-screen shot*/ +#define RETRO_DEVICE_ID_LIGHTGUN_AUX_A 3 +#define RETRO_DEVICE_ID_LIGHTGUN_AUX_B 4 +#define RETRO_DEVICE_ID_LIGHTGUN_START 6 +#define RETRO_DEVICE_ID_LIGHTGUN_SELECT 7 +#define RETRO_DEVICE_ID_LIGHTGUN_AUX_C 8 +#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_UP 9 +#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_DOWN 10 +#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_LEFT 11 +#define RETRO_DEVICE_ID_LIGHTGUN_DPAD_RIGHT 12 +/* deprecated */ +#define RETRO_DEVICE_ID_LIGHTGUN_X 0 /*Relative Position*/ +#define RETRO_DEVICE_ID_LIGHTGUN_Y 1 /*Relative*/ +#define RETRO_DEVICE_ID_LIGHTGUN_CURSOR 3 /*Use Aux:A*/ +#define RETRO_DEVICE_ID_LIGHTGUN_TURBO 4 /*Use Aux:B*/ +#define RETRO_DEVICE_ID_LIGHTGUN_PAUSE 5 /*Use Start*/ + +/* Id values for POINTER. */ +#define RETRO_DEVICE_ID_POINTER_X 0 +#define RETRO_DEVICE_ID_POINTER_Y 1 +#define RETRO_DEVICE_ID_POINTER_PRESSED 2 +#define RETRO_DEVICE_ID_POINTER_COUNT 3 + +/** @} */ + +/* Returned from retro_get_region(). */ +#define RETRO_REGION_NTSC 0 +#define RETRO_REGION_PAL 1 + +/** + * Identifiers for supported languages. + * @see RETRO_ENVIRONMENT_GET_LANGUAGE + */ +enum retro_language +{ + RETRO_LANGUAGE_ENGLISH = 0, + RETRO_LANGUAGE_JAPANESE = 1, + RETRO_LANGUAGE_FRENCH = 2, + RETRO_LANGUAGE_SPANISH = 3, + RETRO_LANGUAGE_GERMAN = 4, + RETRO_LANGUAGE_ITALIAN = 5, + RETRO_LANGUAGE_DUTCH = 6, + RETRO_LANGUAGE_PORTUGUESE_BRAZIL = 7, + RETRO_LANGUAGE_PORTUGUESE_PORTUGAL = 8, + RETRO_LANGUAGE_RUSSIAN = 9, + RETRO_LANGUAGE_KOREAN = 10, + RETRO_LANGUAGE_CHINESE_TRADITIONAL = 11, + RETRO_LANGUAGE_CHINESE_SIMPLIFIED = 12, + RETRO_LANGUAGE_ESPERANTO = 13, + RETRO_LANGUAGE_POLISH = 14, + RETRO_LANGUAGE_VIETNAMESE = 15, + RETRO_LANGUAGE_ARABIC = 16, + RETRO_LANGUAGE_GREEK = 17, + RETRO_LANGUAGE_TURKISH = 18, + RETRO_LANGUAGE_SLOVAK = 19, + RETRO_LANGUAGE_PERSIAN = 20, + RETRO_LANGUAGE_HEBREW = 21, + RETRO_LANGUAGE_ASTURIAN = 22, + RETRO_LANGUAGE_FINNISH = 23, + RETRO_LANGUAGE_INDONESIAN = 24, + RETRO_LANGUAGE_SWEDISH = 25, + RETRO_LANGUAGE_UKRAINIAN = 26, + RETRO_LANGUAGE_CZECH = 27, + RETRO_LANGUAGE_CATALAN_VALENCIA = 28, + RETRO_LANGUAGE_CATALAN = 29, + RETRO_LANGUAGE_BRITISH_ENGLISH = 30, + RETRO_LANGUAGE_HUNGARIAN = 31, + RETRO_LANGUAGE_BELARUSIAN = 32, + RETRO_LANGUAGE_GALICIAN = 33, + RETRO_LANGUAGE_NORWEGIAN = 34, + RETRO_LANGUAGE_LAST, + + /** Defined to ensure that sizeof(retro_language) == sizeof(int). Do not use. */ + RETRO_LANGUAGE_DUMMY = INT_MAX +}; + +/** @defgroup RETRO_MEMORY Memory Types + * @{ + */ + +/* Passed to retro_get_memory_data/size(). + * If the memory type doesn't apply to the + * implementation NULL/0 can be returned. + */ +#define RETRO_MEMORY_MASK 0xff + +/* Regular save RAM. This RAM is usually found on a game cartridge, + * backed up by a battery. + * If save game data is too complex for a single memory buffer, + * the SAVE_DIRECTORY (preferably) or SYSTEM_DIRECTORY environment + * callback can be used. */ +#define RETRO_MEMORY_SAVE_RAM 0 + +/* Some games have a built-in clock to keep track of time. + * This memory is usually just a couple of bytes to keep track of time. + */ +#define RETRO_MEMORY_RTC 1 + +/* System ram lets a frontend peek into a game systems main RAM. */ +#define RETRO_MEMORY_SYSTEM_RAM 2 + +/* Video ram lets a frontend peek into a game systems video RAM (VRAM). */ +#define RETRO_MEMORY_VIDEO_RAM 3 + +/** @} */ + +/* Keysyms used for ID in input state callback when polling RETRO_KEYBOARD. */ +enum retro_key +{ + RETROK_UNKNOWN = 0, + RETROK_FIRST = 0, + RETROK_BACKSPACE = 8, + RETROK_TAB = 9, + RETROK_CLEAR = 12, + RETROK_RETURN = 13, + RETROK_PAUSE = 19, + RETROK_ESCAPE = 27, + RETROK_SPACE = 32, + RETROK_EXCLAIM = 33, + RETROK_QUOTEDBL = 34, + RETROK_HASH = 35, + RETROK_DOLLAR = 36, + RETROK_AMPERSAND = 38, + RETROK_QUOTE = 39, + RETROK_LEFTPAREN = 40, + RETROK_RIGHTPAREN = 41, + RETROK_ASTERISK = 42, + RETROK_PLUS = 43, + RETROK_COMMA = 44, + RETROK_MINUS = 45, + RETROK_PERIOD = 46, + RETROK_SLASH = 47, + RETROK_0 = 48, + RETROK_1 = 49, + RETROK_2 = 50, + RETROK_3 = 51, + RETROK_4 = 52, + RETROK_5 = 53, + RETROK_6 = 54, + RETROK_7 = 55, + RETROK_8 = 56, + RETROK_9 = 57, + RETROK_COLON = 58, + RETROK_SEMICOLON = 59, + RETROK_LESS = 60, + RETROK_EQUALS = 61, + RETROK_GREATER = 62, + RETROK_QUESTION = 63, + RETROK_AT = 64, + RETROK_LEFTBRACKET = 91, + RETROK_BACKSLASH = 92, + RETROK_RIGHTBRACKET = 93, + RETROK_CARET = 94, + RETROK_UNDERSCORE = 95, + RETROK_BACKQUOTE = 96, + RETROK_a = 97, + RETROK_b = 98, + RETROK_c = 99, + RETROK_d = 100, + RETROK_e = 101, + RETROK_f = 102, + RETROK_g = 103, + RETROK_h = 104, + RETROK_i = 105, + RETROK_j = 106, + RETROK_k = 107, + RETROK_l = 108, + RETROK_m = 109, + RETROK_n = 110, + RETROK_o = 111, + RETROK_p = 112, + RETROK_q = 113, + RETROK_r = 114, + RETROK_s = 115, + RETROK_t = 116, + RETROK_u = 117, + RETROK_v = 118, + RETROK_w = 119, + RETROK_x = 120, + RETROK_y = 121, + RETROK_z = 122, + RETROK_LEFTBRACE = 123, + RETROK_BAR = 124, + RETROK_RIGHTBRACE = 125, + RETROK_TILDE = 126, + RETROK_DELETE = 127, + + RETROK_KP0 = 256, + RETROK_KP1 = 257, + RETROK_KP2 = 258, + RETROK_KP3 = 259, + RETROK_KP4 = 260, + RETROK_KP5 = 261, + RETROK_KP6 = 262, + RETROK_KP7 = 263, + RETROK_KP8 = 264, + RETROK_KP9 = 265, + RETROK_KP_PERIOD = 266, + RETROK_KP_DIVIDE = 267, + RETROK_KP_MULTIPLY = 268, + RETROK_KP_MINUS = 269, + RETROK_KP_PLUS = 270, + RETROK_KP_ENTER = 271, + RETROK_KP_EQUALS = 272, + + RETROK_UP = 273, + RETROK_DOWN = 274, + RETROK_RIGHT = 275, + RETROK_LEFT = 276, + RETROK_INSERT = 277, + RETROK_HOME = 278, + RETROK_END = 279, + RETROK_PAGEUP = 280, + RETROK_PAGEDOWN = 281, + + RETROK_F1 = 282, + RETROK_F2 = 283, + RETROK_F3 = 284, + RETROK_F4 = 285, + RETROK_F5 = 286, + RETROK_F6 = 287, + RETROK_F7 = 288, + RETROK_F8 = 289, + RETROK_F9 = 290, + RETROK_F10 = 291, + RETROK_F11 = 292, + RETROK_F12 = 293, + RETROK_F13 = 294, + RETROK_F14 = 295, + RETROK_F15 = 296, + + RETROK_NUMLOCK = 300, + RETROK_CAPSLOCK = 301, + RETROK_SCROLLOCK = 302, + RETROK_RSHIFT = 303, + RETROK_LSHIFT = 304, + RETROK_RCTRL = 305, + RETROK_LCTRL = 306, + RETROK_RALT = 307, + RETROK_LALT = 308, + RETROK_RMETA = 309, + RETROK_LMETA = 310, + RETROK_LSUPER = 311, + RETROK_RSUPER = 312, + RETROK_MODE = 313, + RETROK_COMPOSE = 314, + + RETROK_HELP = 315, + RETROK_PRINT = 316, + RETROK_SYSREQ = 317, + RETROK_BREAK = 318, + RETROK_MENU = 319, + RETROK_POWER = 320, + RETROK_EURO = 321, + RETROK_UNDO = 322, + RETROK_OEM_102 = 323, + + RETROK_BROWSER_BACK = 324, + RETROK_BROWSER_FORWARD = 325, + RETROK_BROWSER_REFRESH = 326, + RETROK_BROWSER_STOP = 327, + RETROK_BROWSER_SEARCH = 328, + RETROK_BROWSER_FAVORITES = 329, + RETROK_BROWSER_HOME = 330, + RETROK_VOLUME_MUTE = 331, + RETROK_VOLUME_DOWN = 332, + RETROK_VOLUME_UP = 333, + RETROK_MEDIA_NEXT = 334, + RETROK_MEDIA_PREV = 335, + RETROK_MEDIA_STOP = 336, + RETROK_MEDIA_PLAY_PAUSE = 337, + RETROK_LAUNCH_MAIL = 338, + RETROK_LAUNCH_MEDIA = 339, + RETROK_LAUNCH_APP1 = 340, + RETROK_LAUNCH_APP2 = 341, + + RETROK_LAST, + + RETROK_DUMMY = INT_MAX /* Ensure sizeof(enum) == sizeof(int) */ +}; + +enum retro_mod +{ + RETROKMOD_NONE = 0x0000, + + RETROKMOD_SHIFT = 0x01, + RETROKMOD_CTRL = 0x02, + RETROKMOD_ALT = 0x04, + RETROKMOD_META = 0x08, + + RETROKMOD_NUMLOCK = 0x10, + RETROKMOD_CAPSLOCK = 0x20, + RETROKMOD_SCROLLOCK = 0x40, + + RETROKMOD_DUMMY = INT_MAX /* Ensure sizeof(enum) == sizeof(int) */ +}; + +/** + * @defgroup RETRO_ENVIRONMENT Environment Callbacks + * @{ + */ + +/** + * This bit indicates that the associated environment call is experimental, + * and may be changed or removed in the future. + * Frontends should mask out this bit before handling the environment call. + */ +#define RETRO_ENVIRONMENT_EXPERIMENTAL 0x10000 + +/** Frontend-internal environment callbacks should include this bit. */ +#define RETRO_ENVIRONMENT_PRIVATE 0x20000 + +/* Environment commands. */ +/** + * Requests the frontend to set the screen rotation. + * + * @param[in] data const unsigned*. + * Valid values are 0, 1, 2, and 3. + * These numbers respectively set the screen rotation to 0, 90, 180, and 270 degrees counter-clockwise. + * @returns \c true if the screen rotation was set successfully. + */ +#define RETRO_ENVIRONMENT_SET_ROTATION 1 + +/** + * Queries whether the core should use overscan or not. + * + * @param[out] data bool*. + * Set to \c true if the core should use overscan, + * \c false if it should be cropped away. + * @returns \c true if the environment call is available. + * Does \em not indicate whether overscan should be used. + * @deprecated As of 2019 this callback is considered deprecated in favor of + * using core options to manage overscan in a more nuanced, core-specific way. + */ +#define RETRO_ENVIRONMENT_GET_OVERSCAN 2 + +/** + * Queries whether the frontend supports frame duping, + * in the form of passing \c NULL to the video frame callback. + * + * @param[out] data bool*. + * Set to \c true if the frontend supports frame duping. + * @returns \c true if the environment call is available. + * @see retro_video_refresh_t + */ +#define RETRO_ENVIRONMENT_GET_CAN_DUPE 3 + +/* + * Environ 4, 5 are no longer supported (GET_VARIABLE / SET_VARIABLES), + * and reserved to avoid possible ABI clash. + */ + +/** + * @brief Displays a user-facing message for a short time. + * + * Use this callback to convey important status messages, + * such as errors or the result of long-running operations. + * For trivial messages or logging, use \c RETRO_ENVIRONMENT_GET_LOG_INTERFACE or \c stderr. + * + * \code{.c} + * void set_message_example(void) + * { + * struct retro_message msg; + * msg.frames = 60 * 5; // 5 seconds + * msg.msg = "Hello world!"; + * + * environ_cb(RETRO_ENVIRONMENT_SET_MESSAGE, &msg); + * } + * \endcode + * + * @deprecated Prefer using \c RETRO_ENVIRONMENT_SET_MESSAGE_EXT for new code, + * as it offers more features. + * Only use this environment call for compatibility with older cores or frontends. + * + * @param[in] data const struct retro_message*. + * Details about the message to show to the user. + * Behavior is undefined if NULL. + * @returns \c true if the environment call is available. + * @see retro_message + * @see RETRO_ENVIRONMENT_GET_LOG_INTERFACE + * @see RETRO_ENVIRONMENT_SET_MESSAGE_EXT + * @see RETRO_ENVIRONMENT_SET_MESSAGE + * @see RETRO_ENVIRONMENT_GET_MESSAGE_INTERFACE_VERSION + * @note The frontend must make its own copy of the message and the underlying string. + */ +#define RETRO_ENVIRONMENT_SET_MESSAGE 6 + +/** + * Requests the frontend to shutdown the core. + * Should only be used if the core can exit on its own, + * such as from a menu item in a game + * or an emulated power-off in an emulator. + * + * @param data Ignored. + * @returns \c true if the environment call is available. + */ +#define RETRO_ENVIRONMENT_SHUTDOWN 7 + +/** + * Gives a hint to the frontend of how demanding this core is on the system. + * For example, reporting a level of 2 means that + * this implementation should run decently on frontends + * of level 2 and above. + * + * It can be used by the frontend to potentially warn + * about too demanding implementations. + * + * The levels are "floating". + * + * This function can be called on a per-game basis, + * as a core may have different demands for different games or settings. + * If called, it should be called in retro_load_game(). + * @param[in] data const unsigned*. +*/ +#define RETRO_ENVIRONMENT_SET_PERFORMANCE_LEVEL 8 + +/** + * Returns the path to the frontend's system directory, + * which can be used to store system-specific configuration + * such as BIOS files or cached data. + * + * @param[out] data const char**. + * Pointer to the \c char* in which the system directory will be saved. + * The string is managed by the frontend and must not be modified or freed by the core. + * May be \c NULL if no system directory is defined, + * in which case the core should find an alternative directory. + * @return \c true if the environment call is available, + * even if the value returned in \c data is NULL. + * @note Historically, some cores would use this folder for save data such as memory cards or SRAM. + * This is now discouraged in favor of \c RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY. + * @see RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY + */ +#define RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY 9 + +/** + * Sets the internal pixel format used by the frontend for rendering. + * The default pixel format is \c RETRO_PIXEL_FORMAT_0RGB1555 for compatibility reasons, + * although it's considered deprecated and shouldn't be used by new code. + * + * @param[in] data const enum retro_pixel_format *. + * Pointer to the pixel format to use. + * @returns \c true if the pixel format was set successfully, + * \c false if it's not supported or this callback is unavailable. + * @note This function should be called inside \c retro_load_game() + * or retro_get_system_av_info(). + * @see retro_pixel_format + */ +#define RETRO_ENVIRONMENT_SET_PIXEL_FORMAT 10 + +/** + * Sets an array of input descriptors for the frontend + * to present to the user for configuring the core's controls. + * + * This function can be called at any time, + * preferably early in the core's life cycle. + * Ideally, no later than \c retro_load_game(). + * + * @param[in] data const struct retro_input_descriptor *. + * An array of input descriptors terminated by one whose + * \c retro_input_descriptor::description field is set to \c NULL. + * Behavior is undefined if \c NULL. + * @return \c true if the environment call is recognized. + * @see retro_input_descriptor + */ +#define RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS 11 + +/** + * Sets a callback function used to notify the core about keyboard events. + * This should only be used for cores that specifically need keyboard input, + * such as for home computer emulators or games with text entry. + * + * @param[in] data const struct retro_keyboard_callback *. + * Pointer to the callback function. + * Behavior is undefined if NULL. + * @return \c true if the environment call is recognized. + * @see retro_keyboard_callback + * @see retro_key + */ +#define RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK 12 + +/** + * Sets an interface that the frontend can use to insert and remove disks + * from the emulated console's disk drive. + * Can be used for optical disks, floppy disks, or any other game storage medium + * that can be swapped at runtime. + * + * This is intended for multi-disk games that expect the player + * to manually swap disks at certain points in the game. + * + * @deprecated Prefer using \c RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE + * over this environment call, as it supports additional features. + * Only use this callback to maintain compatibility + * with older cores or frontends. + * + * @param[in] data const struct retro_disk_control_callback *. + * Pointer to the callback functions to use. + * May be \c NULL, in which case the existing disk callback is deregistered. + * @return \c true if this environment call is available, + * even if \c data is \c NULL. + * @see retro_disk_control_callback + * @see RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE + */ +#define RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE 13 + +/** + * Requests that a frontend enable a particular hardware rendering API. + * + * If successful, the frontend will create a context (and other related resources) + * that the core can use for rendering. + * The framebuffer will be at least as large as + * the maximum dimensions provided in retro_get_system_av_info. + * + * @param[in, out] data struct retro_hw_render_callback *. + * Pointer to the hardware render callback struct. + * Used to define callbacks for the hardware-rendering life cycle, + * as well as to request a particular rendering API. + * @return \c true if the environment call is recognized + * and the requested rendering API is supported. + * \c false if \c data is \c NULL + * or the frontend can't provide the requested rendering API. + * @see retro_hw_render_callback + * @see retro_video_refresh_t + * @see RETRO_ENVIRONMENT_GET_PREFERRED_HW_RENDER + * @note Should be called in retro_load_game(). + * @note If HW rendering is used, pass only \c RETRO_HW_FRAME_BUFFER_VALID or + * \c NULL to retro_video_refresh_t. + */ +#define RETRO_ENVIRONMENT_SET_HW_RENDER 14 + +/** + * Retrieves a core option's value from the frontend. + * \c retro_variable::key should be set to an option key + * that was previously set in \c RETRO_ENVIRONMENT_SET_VARIABLES + * (or a similar environment call). + * + * @param[in,out] data struct retro_variable *. + * Pointer to a single \c retro_variable struct. + * See the documentation for \c retro_variable for details + * on which fields are set by the frontend or core. + * May be \c NULL. + * @returns \c true if the environment call is available, + * even if \c data is \c NULL or the key it specifies is not found. + * @note Passing \c NULL in to \c data can be useful to + * test for support of this environment call without looking up any variables. + * @see retro_variable + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + * @see RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE + */ +#define RETRO_ENVIRONMENT_GET_VARIABLE 15 + +/** + * Notifies the frontend of the core's available options. + * + * The core may check these options later using \c RETRO_ENVIRONMENT_GET_VARIABLE. + * The frontend may also present these options to the user + * in its own configuration UI. + * + * This should be called the first time as early as possible, + * ideally in \c retro_set_environment. + * The core may later call this function again + * to communicate updated options to the frontend, + * but the number of core options must not change. + * + * Here's an example that sets two options. + * + * @code + * void set_variables_example(void) + * { + * struct retro_variable options[] = { + * { "foo_speedhack", "Speed hack; false|true" }, // false by default + * { "foo_displayscale", "Display scale factor; 1|2|3|4" }, // 1 by default + * { NULL, NULL }, + * }; + * + * environ_cb(RETRO_ENVIRONMENT_SET_VARIABLES, &options); + * } + * @endcode + * + * The possible values will generally be displayed and stored as-is by the frontend. + * + * @deprecated Prefer using \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 for new code, + * as it offers more features such as categories and translation. + * Only use this environment call to maintain compatibility + * with older frontends or cores. + * @note Keep the available options (and their possible values) as low as possible; + * it should be feasible to cycle through them without a keyboard. + * @param[in] data const struct retro_variable *. + * Pointer to an array of \c retro_variable structs that define available core options, + * terminated by a { NULL, NULL } element. + * The frontend must maintain its own copy of this array. + * + * @returns \c true if the environment call is available, + * even if \c data is NULL. + * @see retro_variable + * @see RETRO_ENVIRONMENT_GET_VARIABLE + * @see RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + */ +#define RETRO_ENVIRONMENT_SET_VARIABLES 16 + +/** + * Queries whether at least one core option was updated by the frontend + * since the last call to \ref RETRO_ENVIRONMENT_GET_VARIABLE. + * This typically means that the user opened the core options menu and made some changes. + * + * Cores usually call this each frame before the core's main emulation logic. + * Specific options can then be queried with \ref RETRO_ENVIRONMENT_GET_VARIABLE. + * + * @param[out] data bool *. + * Set to \c true if at least one core option was updated + * since the last call to \ref RETRO_ENVIRONMENT_GET_VARIABLE. + * Behavior is undefined if this pointer is \c NULL. + * @returns \c true if the environment call is available. + * @see RETRO_ENVIRONMENT_GET_VARIABLE + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + */ +#define RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE 17 + +/** + * Notifies the frontend that this core can run without loading any content, + * such as when emulating a console that has built-in software. + * When a core is loaded without content, + * \c retro_load_game receives an argument of NULL. + * This should be called within \c retro_set_environment() only. + * + * @param[in] data const bool *. + * Pointer to a single \c bool that indicates whether this frontend can run without content. + * Can point to a value of \c false but this isn't necessary, + * as contentless support is opt-in. + * The behavior is undefined if \c data is NULL. + * @returns \c true if the environment call is available. + * @see retro_load_game + */ +#define RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME 18 + +/** + * Retrieves the absolute path from which this core was loaded. + * Useful when loading assets from paths relative to the core, + * as is sometimes the case when using RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME. + * + * @param[out] data const char **. + * Pointer to a string in which the core's path will be saved. + * The string is managed by the frontend and must not be modified or freed by the core. + * May be \c NULL if the core is statically linked to the frontend + * or if the core's path otherwise cannot be determined. + * Behavior is undefined if \c data is NULL. + * @returns \c true if the environment call is available. + */ +#define RETRO_ENVIRONMENT_GET_LIBRETRO_PATH 19 + +/* Environment call 20 was an obsolete version of SET_AUDIO_CALLBACK. + * It was not used by any known core at the time, and was removed from the API. + * The number 20 is reserved to prevent ABI clashes. + */ + +/** + * Sets a callback that notifies the core of how much time has passed + * since the last iteration of retro_run. + * If the frontend is not running the core in real time + * (e.g. it's frame-stepping or running in slow motion), + * then the reference value will be provided to the callback instead. + * + * @param[in] data const struct retro_frame_time_callback *. + * Pointer to a single \c retro_frame_time_callback struct. + * Behavior is undefined if \c data is NULL. + * @returns \c true if the environment call is available. + * @note Frontends may disable this environment call in certain situations. + * It will return \c false in those cases. + * @see retro_frame_time_callback + */ +#define RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK 21 + +/** + * Registers a set of functions that the frontend can use + * to tell the core it's ready for audio output. + * + * It is intended for games that feature asynchronous audio. + * It should not be used for emulators unless their audio is asynchronous. + * + * + * The callback only notifies about writability; the libretro core still + * has to call the normal audio callbacks + * to write audio. The audio callbacks must be called from within the + * notification callback. + * The amount of audio data to write is up to the core. + * Generally, the audio callback will be called continously in a loop. + * + * A frontend may disable this callback in certain situations. + * The core must be able to render audio with the "normal" interface. + * + * @param[in] data const struct retro_audio_callback *. + * Pointer to a set of functions that the frontend will call to notify the core + * when it's ready to receive audio data. + * May be \c NULL, in which case the frontend will return + * whether this environment callback is available. + * @return \c true if this environment call is available, + * even if \c data is \c NULL. + * @warning The provided callbacks can be invoked from any thread, + * so their implementations \em must be thread-safe. + * @note If a core uses this callback, + * it should also use RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK. + * @see retro_audio_callback + * @see retro_audio_sample_t + * @see retro_audio_sample_batch_t + * @see RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK + */ +#define RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK 22 + +/** + * Gets an interface that a core can use to access a controller's rumble motors. + * + * The interface supports two independently-controlled motors, + * one strong and one weak. + * + * Should be called from either \c retro_init() or \c retro_load_game(), + * but not from \c retro_set_environment(). + * + * @param[out] data struct retro_rumble_interface *. + * Pointer to the interface struct. + * Behavior is undefined if \c NULL. + * @returns \c true if the environment call is available, + * even if the current device doesn't support vibration. + * @see retro_rumble_interface + * @defgroup GET_RUMBLE_INTERFACE Rumble Interface + */ +#define RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE 23 + +/** + * Returns the frontend's supported input device types. + * + * The supported device types are returned as a bitmask, + * with each value of \ref RETRO_DEVICE corresponding to a bit. + * + * Should only be called in \c retro_run(). + * + * @code + * #define REQUIRED_DEVICES ((1 << RETRO_DEVICE_JOYPAD) | (1 << RETRO_DEVICE_ANALOG)) + * void get_input_device_capabilities_example(void) + * { + * uint64_t capabilities; + * environ_cb(RETRO_ENVIRONMENT_GET_INPUT_DEVICE_CAPABILITIES, &capabilities); + * if ((capabilities & REQUIRED_DEVICES) == REQUIRED_DEVICES) + * printf("Joypad and analog device types are supported"); + * } + * @endcode + * + * @param[out] data uint64_t *. + * Pointer to a bitmask of supported input device types. + * If the frontend supports a particular \c RETRO_DEVICE_* type, + * then the bit (1 << RETRO_DEVICE_*) will be set. + * + * Each bit represents a \c RETRO_DEVICE constant, + * e.g. bit 1 represents \c RETRO_DEVICE_JOYPAD, + * bit 2 represents \c RETRO_DEVICE_MOUSE, and so on. + * + * Bits that do not correspond to known device types will be set to zero + * and are reserved for future use. + * + * Behavior is undefined if \c NULL. + * @returns \c true if the environment call is available. + * @note If the frontend supports multiple input drivers, + * availability of this environment call (and the reported capabilities) + * may depend on the active driver. + * @see RETRO_DEVICE + */ +#define RETRO_ENVIRONMENT_GET_INPUT_DEVICE_CAPABILITIES 24 + +/** + * Returns an interface that the core can use to access and configure available sensors, + * such as an accelerometer or gyroscope. + * + * @param[out] data struct retro_sensor_interface *. + * Pointer to the sensor interface that the frontend will populate. + * Behavior is undefined if is \c NULL. + * @returns \c true if the environment call is available, + * even if the device doesn't have any supported sensors. + * @see retro_sensor_interface + * @see retro_sensor_action + * @see RETRO_SENSOR + * @addtogroup RETRO_SENSOR + */ +#define RETRO_ENVIRONMENT_GET_SENSOR_INTERFACE (25 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Gets an interface to the device's video camera. + * + * The frontend delivers new video frames via a user-defined callback + * that runs in the same thread as \c retro_run(). + * Should be called in \c retro_load_game(). + * + * @param[in,out] data struct retro_camera_callback *. + * Pointer to the camera driver interface. + * Some fields in the struct must be filled in by the core, + * others are provided by the frontend. + * Behavior is undefined if \c NULL. + * @returns \c true if this environment call is available, + * even if an actual camera isn't. + * @note This API only supports one video camera at a time. + * If the device provides multiple cameras (e.g. inner/outer cameras on a phone), + * the frontend will choose one to use. + * @see retro_camera_callback + * @see RETRO_ENVIRONMENT_SET_HW_RENDER + */ +#define RETRO_ENVIRONMENT_GET_CAMERA_INTERFACE (26 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Gets an interface that the core can use for cross-platform logging. + * Certain platforms don't have a console or stderr, + * or they have their own preferred logging methods. + * The frontend itself may also display log output. + * + * @attention This should not be used for information that the player must immediately see, + * such as major errors or warnings. + * In most cases, this is best for information that will help you (the developer) + * identify problems when debugging or providing support. + * Unless a core or frontend is intended for advanced users, + * the player might not check (or even know about) their logs. + * + * @param[out] data struct retro_log_callback *. + * Pointer to the callback where the function pointer will be saved. + * Behavior is undefined if \c data is NULL. + * @returns \c true if the environment call is available. + * @see retro_log_callback + * @note Cores can fall back to \c stderr if this interface is not available. + */ +#define RETRO_ENVIRONMENT_GET_LOG_INTERFACE 27 + +/** + * Returns an interface that the core can use for profiling code + * and to access performance-related information. + * + * This callback supports performance counters, a high-resolution timer, + * and listing available CPU features (mostly SIMD instructions). + * + * @param[out] data struct retro_perf_callback *. + * Pointer to the callback interface. + * Behavior is undefined if \c NULL. + * @returns \c true if the environment call is available. + * @see retro_perf_callback + */ +#define RETRO_ENVIRONMENT_GET_PERF_INTERFACE 28 + +/** + * Returns an interface that the core can use to retrieve the device's location, + * including its current latitude and longitude. + * + * @param[out] data struct retro_location_callback *. + * Pointer to the callback interface. + * Behavior is undefined if \c NULL. + * @return \c true if the environment call is available, + * even if there's no location information available. + * @see retro_location_callback + */ +#define RETRO_ENVIRONMENT_GET_LOCATION_INTERFACE 29 + +/** + * @deprecated An obsolete alias to \c RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY kept for compatibility. + * @see RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY + **/ +#define RETRO_ENVIRONMENT_GET_CONTENT_DIRECTORY 30 + +/** + * Returns the frontend's "core assets" directory, + * which can be used to store assets that the core needs + * such as art assets or level data. + * + * @param[out] data const char **. + * Pointer to a string in which the core assets directory will be saved. + * This string is managed by the frontend and must not be modified or freed by the core. + * May be \c NULL if no core assets directory is defined, + * in which case the core should find an alternative directory. + * Behavior is undefined if \c data is NULL. + * @returns \c true if the environment call is available, + * even if the value returned in \c data is NULL. + */ +#define RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY 30 + +/** + * Returns the frontend's save data directory, if available. + * This directory should be used to store game-specific save data, + * including memory card images. + * + * Although libretro provides an interface for cores to expose SRAM to the frontend, + * not all cores can support it correctly. + * In this case, cores should use this environment callback + * to save their game data to disk manually. + * + * Cores that use this environment callback + * should flush their save data to disk periodically and when unloading. + * + * @param[out] data const char **. + * Pointer to the string in which the save data directory will be saved. + * This string is managed by the frontend and must not be modified or freed by the core. + * May return \c NULL if no save data directory is defined. + * Behavior is undefined if \c data is NULL. + * @returns \c true if the environment call is available, + * even if the value returned in \c data is NULL. + * @note Early libretro cores used \c RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY for save data. + * This is still supported for backwards compatibility, + * but new cores should use this environment call instead. + * \c RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY should be used for game-agnostic data + * such as BIOS files or core-specific configuration. + * @note The returned directory may or may not be the same + * as the one used for \c retro_get_memory_data. + * + * @see retro_get_memory_data + * @see RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY + */ +#define RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY 31 + +/** + * Sets new video and audio parameters for the core. + * This can only be called from within retro_run. + * + * This environment call may entail a full reinitialization of the frontend's audio/video drivers, + * hence it should \em only be used if the core needs to make drastic changes + * to audio/video parameters. + * + * This environment call should \em not be used when: + *
    + *
  • Changing the emulated system's internal resolution, + * within the limits defined by the existing values of \c max_width and \c max_height. + * Use \c RETRO_ENVIRONMENT_SET_GEOMETRY instead, + * and adjust \c retro_get_system_av_info to account fo + * supported scale factors and screen layouts + * when computing \c max_width and \c max_height. + * Only use this environment call if \c max_width or \c max_height needs to increase. + *
  • Adjusting the screen's aspect ratio, + * e.g. when changing the layout of the screen(s). + * Use \c RETRO_ENVIRONMENT_SET_GEOMETRY or \c RETRO_ENVIRONMENT_SET_ROTATION instead. + *
+ * + * The frontend will reinitialize its audio and video drivers within this callback; + * after that happens, audio and video callbacks will target the newly-initialized driver, + * even within the same \c retro_run call. + * + * This callback makes it possible to support configurable resolutions + * while avoiding the need to compute the "worst case" values of \c max_width and \c max_height. + * + * @param[in] data const struct retro_system_av_info *. + * Pointer to the new video and audio parameters that the frontend should adopt. + * @returns \c true if the environment call is available + * and the new av_info struct was accepted. + * \c false if the environment call is unavailable or \c data is NULL. + * @see retro_system_av_info + * @see RETRO_ENVIRONMENT_SET_GEOMETRY + */ +#define RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO 32 + +/** + * Provides an interface that a frontend can use + * to get function pointers from the core. + * + * This allows cores to define their own extensions to the libretro API, + * or to expose implementations of a frontend's libretro extensions. + * + * @param[in] data const struct retro_get_proc_address_interface *. + * Pointer to the interface that the frontend can use to get function pointers from the core. + * The frontend must maintain its own copy of this interface. + * @returns \c true if the environment call is available + * and the returned interface was accepted. + * @note The provided interface may be called at any time, + * even before this environment call returns. + * @note Extensions should be prefixed with the name of the frontend or core that defines them. + * For example, a frontend named "foo" that defines a debugging extension + * should expect the core to define functions prefixed with "foo_debug_". + * @warning If a core wants to use this environment call, + * it \em must do so from within \c retro_set_environment(). + * @see retro_get_proc_address_interface + */ +#define RETRO_ENVIRONMENT_SET_PROC_ADDRESS_CALLBACK 33 + +/** + * Registers a core's ability to handle "subsystems", + * which are secondary platforms that augment a core's primary emulated hardware. + * + * A core doesn't need to emulate a secondary platform + * in order to use it as a subsystem; + * as long as it can load a secondary file for some practical use, + * then this environment call is most likely suitable. + * + * Possible use cases of a subsystem include: + * + * \li Installing software onto an emulated console's internal storage, + * such as the Nintendo DSi. + * \li Emulating accessories that are used to support another console's games, + * such as the Super Game Boy or the N64 Transfer Pak. + * \li Inserting a secondary ROM into a console + * that features multiple cartridge ports, + * such as the Nintendo DS's Slot-2. + * \li Loading a save data file created and used by another core. + * + * Cores should \em not use subsystems for: + * + * \li Emulators that support multiple "primary" platforms, + * such as a Game Boy/Game Boy Advance core + * or a Sega Genesis/Sega CD/32X core. + * Use \c retro_system_content_info_override, \c retro_system_info, + * and/or runtime detection instead. + * \li Selecting different memory card images. + * Use dynamically-populated core options instead. + * \li Different variants of a single console, + * such the Game Boy vs. the Game Boy Color. + * Use core options or runtime detection instead. + * \li Games that span multiple disks. + * Use \c RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE + * and m3u-formatted playlists instead. + * \li Console system files (BIOS, firmware, etc.). + * Use \c RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY + * and a common naming convention instead. + * + * When the frontend loads a game via a subsystem, + * it must call \c retro_load_game_special() instead of \c retro_load_game(). + * + * @param[in] data const struct retro_subsystem_info *. + * Pointer to an array of subsystem descriptors, + * terminated by a zeroed-out \c retro_subsystem_info struct. + * The frontend should maintain its own copy + * of this array and the strings within it. + * Behavior is undefined if \c NULL. + * @returns \c true if this environment call is available. + * @note This environment call \em must be called from within \c retro_set_environment(), + * as frontends may need the registered information before loading a game. + * @see retro_subsystem_info + * @see retro_load_game_special + */ +#define RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO 34 + +/** + * Declares one or more types of controllers supported by this core. + * The frontend may then allow the player to select one of these controllers in its menu. + * + * Many consoles had controllers that came in different versions, + * were extensible with peripherals, + * or could be held in multiple ways; + * this environment call can be used to represent these differences + * and adjust the core's behavior to match. + * + * Possible use cases include: + * + * \li Supporting different classes of a single controller that supported their own sets of games. + * For example, the SNES had two different lightguns (the Super Scope and the Justifier) + * whose games were incompatible with each other. + * \li Representing a platform's alternative controllers. + * For example, several platforms had music/rhythm games that included controllers + * shaped like musical instruments. + * \li Representing variants of a standard controller with additional inputs. + * For example, numerous consoles in the 90's introduced 6-button controllers for fighting games, + * steering wheels for racing games, + * or analog sticks for 3D platformers. + * \li Representing add-ons for consoles or standard controllers. + * For example, the 3DS had a Circle Pad Pro attachment that added a second analog stick. + * \li Selecting different configurations for a single controller. + * For example, the Wii Remote could be held sideways like a traditional game pad + * or in one hand like a wand. + * \li Providing multiple ways to simulate the experience of using a particular controller. + * For example, the Game Boy Advance featured several games + * with motion or light sensors in their cartridges; + * a core could provide controller configurations + * that allow emulating the sensors with either analog axes + * or with their host device's sensors. + * + * Should be called in retro_load_game. + * The frontend must maintain its own copy of the provided array, + * including all strings and subobjects. + * A core may exclude certain controllers for known incompatible games. + * + * When the frontend changes the active device for a particular port, + * it must call \c retro_set_controller_port_device() with that port's index + * and one of the IDs defined in its retro_controller_info::types field. + * + * Input ports are generally associated with different players + * (and the frontend's UI may reflect this with "Player 1" labels), + * but this is not required. + * Some games use multiple controllers for a single player, + * or some cores may use port indexes to represent an emulated console's + * alternative input peripherals. + * + * @param[in] data const struct retro_controller_info *. + * Pointer to an array of controller types defined by this core, + * terminated by a zeroed-out \c retro_controller_info. + * Each element of this array represents a controller port on the emulated device. + * Behavior is undefined if \c NULL. + * @returns \c true if this environment call is available. + * @see retro_controller_info + * @see retro_set_controller_port_device + * @see RETRO_DEVICE_SUBCLASS + */ +#define RETRO_ENVIRONMENT_SET_CONTROLLER_INFO 35 + +/** + * Notifies the frontend of the address spaces used by the core's emulated hardware, + * and of the memory maps within these spaces. + * This can be used by the frontend to provide cheats, achievements, or debugging capabilities. + * Should only be used by emulators, as it makes little sense for game engines. + * + * @note Cores should also expose these address spaces + * through retro_get_memory_data and \c retro_get_memory_size if applicable; + * this environment call is not intended to replace those two functions, + * as the emulated hardware may feature memory regions outside of its own address space + * that are nevertheless useful for the frontend. + * + * @param[in] data const struct retro_memory_map *. + * Pointer to a single memory-map listing. + * The frontend must maintain its own copy of this object and its contents, + * including strings and nested objects. + * Behavior is undefined if \c NULL. + * @returns \c true if this environment call is available. + * @see retro_memory_map + * @see retro_get_memory_data + * @see retro_memory_descriptor + */ +#define RETRO_ENVIRONMENT_SET_MEMORY_MAPS (36 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Resizes the viewport without reinitializing the video driver. + * + * Similar to \c RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO, + * but any changes that would require video reinitialization will not be performed. + * Can only be called from within \c retro_run(). + * + * This environment call allows a core to revise the size of the viewport at will, + * which can be useful for emulated platforms that support dynamic resolution changes + * or for cores that support multiple screen layouts. + * + * A frontend must guarantee that this environment call completes in + * constant time. + * + * @param[in] data const struct retro_game_geometry *. + * Pointer to the new video parameters that the frontend should adopt. + * \c retro_game_geometry::max_width and \c retro_game_geometry::max_height + * will be ignored. + * Behavior is undefined if \c data is NULL. + * @return \c true if the environment call is available. + * @see RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO + */ +#define RETRO_ENVIRONMENT_SET_GEOMETRY 37 + +/** + * Returns the name of the user, if possible. + * This callback is suitable for cores that offer personalization, + * such as online facilities or user profiles on the emulated system. + * @param[out] data const char **. + * Pointer to the user name string. + * May be \c NULL, in which case the core should use a default name. + * The returned pointer is owned by the frontend and must not be modified or freed by the core. + * Behavior is undefined if \c NULL. + * @returns \c true if the environment call is available, + * even if the frontend couldn't provide a name. + */ +#define RETRO_ENVIRONMENT_GET_USERNAME 38 + +/** + * Returns the frontend's configured language. + * It can be used to localize the core's UI, + * or to customize the emulated firmware if applicable. + * + * @param[out] data retro_language *. + * Pointer to the language identifier. + * Behavior is undefined if \c NULL. + * @returns \c true if the environment call is available. + * @note The returned language may not be the same as the operating system's language. + * Cores should fall back to the operating system's language (or to English) + * if the environment call is unavailable or the returned language is unsupported. + * @see retro_language + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL + */ +#define RETRO_ENVIRONMENT_GET_LANGUAGE 39 + +/** + * Returns a frontend-managed framebuffer + * that the core may render directly into + * + * This environment call is provided as an optimization + * for cores that use software rendering + * (i.e. that don't use \refitem RETRO_ENVIRONMENT_SET_HW_RENDER "a graphics hardware API"); + * specifically, the intended use case is to allow a core + * to render directly into frontend-managed video memory, + * avoiding the bandwidth use that copying a whole framebuffer from core to video memory entails. + * + * Must be called every frame if used, + * as this may return a different framebuffer each frame + * (e.g. for swap chains). + * However, a core may render to a different buffer even if this call succeeds. + * + * @param[in,out] data struct retro_framebuffer *. + * Pointer to a frontend's frame buffer and accompanying data. + * Some fields are set by the core, others are set by the frontend. + * Only guaranteed to be valid for the duration of the current \c retro_run call, + * and must not be used afterwards. + * Behavior is undefined if \c NULL. + * @return \c true if the environment call was recognized + * and the framebuffer was successfully returned. + * @see retro_framebuffer + */ +#define RETRO_ENVIRONMENT_GET_CURRENT_SOFTWARE_FRAMEBUFFER (40 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Returns an interface for accessing the data of specific rendering APIs. + * Not all hardware rendering APIs support or need this. + * + * The details of these interfaces are specific to each rendering API. + * + * @note \c retro_hw_render_callback::context_reset must be called by the frontend + * before this environment call can be used. + * Additionally, the contents of the returned interface are invalidated + * after \c retro_hw_render_callback::context_destroyed has been called. + * @param[out] data const struct retro_hw_render_interface **. + * The render interface for the currently-enabled hardware rendering API, if any. + * The frontend will store a pointer to the interface at the address provided here. + * The returned interface is owned by the frontend and must not be modified or freed by the core. + * Behavior is undefined if \c NULL. + * @return \c true if this environment call is available, + * the active graphics API has a libretro rendering interface, + * and the frontend is able to return said interface. + * \c false otherwise. + * @see RETRO_ENVIRONMENT_SET_HW_RENDER + * @see retro_hw_render_interface + * @note Since not every libretro-supported hardware rendering API + * has a \c retro_hw_render_interface implementation, + * a result of \c false is not necessarily an error. + */ +#define RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE (41 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Explicitly notifies the frontend of whether this core supports achievements. + * The core must expose its emulated address space via + * \c retro_get_memory_data or \c RETRO_ENVIRONMENT_GET_MEMORY_MAPS. + * Must be called before the first call to retro_run. + * + * If \ref retro_get_memory_data returns a valid address + * but this environment call is not used, + * the frontend (at its discretion) may or may not opt in the core to its achievements support. + * whether this core is opted in to the frontend's achievement support + * is left to the frontend's discretion. + * @param[in] data const bool *. + * Pointer to a single \c bool that indicates whether this core supports achievements. + * Behavior is undefined if \c data is NULL. + * @returns \c true if the environment call is available. + * @see RETRO_ENVIRONMENT_SET_MEMORY_MAPS + * @see retro_get_memory_data + */ +#define RETRO_ENVIRONMENT_SET_SUPPORT_ACHIEVEMENTS (42 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Defines an interface that the frontend can use + * to ask the core for the parameters it needs for a hardware rendering context. + * The exact semantics depend on \ref RETRO_ENVIRONMENT_SET_HW_RENDER "the active rendering API". + * Will be used some time after \c RETRO_ENVIRONMENT_SET_HW_RENDER is called, + * but before \c retro_hw_render_callback::context_reset is called. + * + * @param[in] data const struct retro_hw_render_context_negotiation_interface *. + * Pointer to the context negotiation interface. + * Will be populated by the frontend. + * Behavior is undefined if \c NULL. + * @return \c true if this environment call is supported, + * even if the current graphics API doesn't use + * a context negotiation interface (in which case the argument is ignored). + * @see retro_hw_render_context_negotiation_interface + * @see RETRO_ENVIRONMENT_GET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_SUPPORT + * @see RETRO_ENVIRONMENT_SET_HW_RENDER + */ +#define RETRO_ENVIRONMENT_SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE (43 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Notifies the frontend of any quirks associated with serialization. + * + * Should be set in either \c retro_init or \c retro_load_game, but not both. + * @param[in, out] data uint64_t *. + * Pointer to the core's serialization quirks. + * The frontend will set the flags of the quirks it supports + * and clear the flags of those it doesn't. + * Behavior is undefined if \c NULL. + * @return \c true if this environment call is supported. + * @see retro_serialize + * @see retro_unserialize + * @see RETRO_SERIALIZATION_QUIRK + */ +#define RETRO_ENVIRONMENT_SET_SERIALIZATION_QUIRKS 44 + +/** + * The frontend will try to use a "shared" context when setting up a hardware context. + * Mostly applicable to OpenGL. + * + * In order for this to have any effect, + * the core must call \c RETRO_ENVIRONMENT_SET_HW_RENDER at some point + * if it hasn't already. + * + * @param data Ignored. + * @returns \c true if the environment call is available + * and the frontend supports shared hardware contexts. + */ +#define RETRO_ENVIRONMENT_SET_HW_SHARED_CONTEXT (44 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Returns an interface that the core can use to access the file system. + * Should be called as early as possible. + * + * @param[in,out] data struct retro_vfs_interface_info *. + * Information about the desired VFS interface, + * as well as the interface itself. + * Behavior is undefined if \c NULL. + * @return \c true if this environment call is available + * and the frontend can provide a VFS interface of the requested version or newer. + * @see retro_vfs_interface_info + * @see file_path + * @see retro_dirent + * @see file_stream + */ +#define RETRO_ENVIRONMENT_GET_VFS_INTERFACE (45 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Returns an interface that the core can use + * to set the state of any accessible device LEDs. + * + * @param[out] data struct retro_led_interface *. + * Pointer to the LED interface that the frontend will populate. + * May be \c NULL, in which case the frontend will only return + * whether this environment callback is available. + * @returns \c true if the environment call is available, + * even if \c data is \c NULL + * or no LEDs are accessible. + * @see retro_led_interface + */ +#define RETRO_ENVIRONMENT_GET_LED_INTERFACE (46 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Returns hints about certain steps that the core may skip for this frame. + * + * A frontend may not need a core to generate audio or video in certain situations; + * this environment call sets a bitmask that indicates + * which steps the core may skip for this frame. + * + * This can be used to increase performance for some frontend features. + * + * @note Emulation accuracy should not be compromised; + * for example, if a core emulates a platform that supports display capture + * (i.e. looking at its own VRAM), then it should perform its rendering as normal + * unless it can prove that the emulated game is not using display capture. + * + * @param[out] data retro_av_enable_flags *. + * Pointer to the bitmask of steps that the frontend will skip. + * Other bits are set to zero and are reserved for future use. + * If \c NULL, the frontend will only return whether this environment callback is available. + * @returns \c true if the environment call is available, + * regardless of the value output to \c data. + * If \c false, the core should assume that the frontend will not skip any steps. + * @see retro_av_enable_flags + */ +#define RETRO_ENVIRONMENT_GET_AUDIO_VIDEO_ENABLE (47 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Gets an interface that the core can use for raw MIDI I/O. + * + * @param[out] data struct retro_midi_interface *. + * Pointer to the MIDI interface. + * May be \c NULL. + * @return \c true if the environment call is available, + * even if \c data is \c NULL. + * @see retro_midi_interface + */ +#define RETRO_ENVIRONMENT_GET_MIDI_INTERFACE (48 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Asks the frontend if it's currently in fast-forward mode. + * @param[out] data bool *. + * Set to \c true if the frontend is currently fast-forwarding its main loop. + * Behavior is undefined if \c data is NULL. + * @returns \c true if this environment call is available, + * regardless of the value returned in \c data. + * + * @see RETRO_ENVIRONMENT_SET_FASTFORWARDING_OVERRIDE + */ +#define RETRO_ENVIRONMENT_GET_FASTFORWARDING (49 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Returns the refresh rate the frontend is targeting, in Hz. + * The intended use case is for the core to use the result to select an ideal refresh rate. + * + * @param[out] data float *. + * Pointer to the \c float in which the frontend will store its target refresh rate. + * Behavior is undefined if \c data is NULL. + * @return \c true if this environment call is available, + * regardless of the value returned in \c data. +*/ +#define RETRO_ENVIRONMENT_GET_TARGET_REFRESH_RATE (50 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Returns whether the frontend can return the state of all buttons at once as a bitmask, + * rather than requiring a series of individual calls to \c retro_input_state_t. + * + * If this callback returns \c true, + * you can get the state of all buttons by passing \c RETRO_DEVICE_ID_JOYPAD_MASK + * as the \c id parameter to \c retro_input_state_t. + * Bit #N represents the RETRO_DEVICE_ID_JOYPAD constant of value N, + * e.g. (1 << RETRO_DEVICE_ID_JOYPAD_A) represents the A button. + * + * @param data Ignored. + * @returns \c true if the frontend can report the complete digital joypad state as a bitmask. + * @see retro_input_state_t + * @see RETRO_DEVICE_JOYPAD + * @see RETRO_DEVICE_ID_JOYPAD_MASK + */ +#define RETRO_ENVIRONMENT_GET_INPUT_BITMASKS (51 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Returns the version of the core options API supported by the frontend. + * + * Over the years, libretro has used several interfaces + * for allowing cores to define customizable options. + * \ref SET_CORE_OPTIONS_V2 "Version 2 of the interface" + * is currently preferred due to its extra features, + * but cores and frontends should strive to support + * versions \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS "1" + * and \ref RETRO_ENVIRONMENT_SET_VARIABLES "0" as well. + * This environment call provides the information that cores need for that purpose. + * + * If this environment call returns \c false, + * then the core should assume version 0 of the core options API. + * + * @param[out] data unsigned *. + * Pointer to the integer that will store the frontend's + * supported core options API version. + * Behavior is undefined if \c NULL. + * @returns \c true if the environment call is available, + * \c false otherwise. + * @see RETRO_ENVIRONMENT_SET_VARIABLES + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + */ +#define RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION 52 + +/** + * @copybrief RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + * + * @deprecated This environment call has been superseded + * by RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2, + * which supports categorizing options into groups. + * This environment call should only be used to maintain compatibility + * with older cores and frontends. + * + * This environment call is intended to replace \c RETRO_ENVIRONMENT_SET_VARIABLES, + * and should only be called if \c RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION + * returns an API version of at least 1. + * + * This should be called the first time as early as possible, + * ideally in \c retro_set_environment (but \c retro_load_game is acceptable). + * It may then be called again later to update + * the core's options and their associated values, + * as long as the number of options doesn't change + * from the number given in the first call. + * + * The core can retrieve option values at any time with \c RETRO_ENVIRONMENT_GET_VARIABLE. + * If a saved value for a core option doesn't match the option definition's values, + * the frontend may treat it as incorrect and revert to the default. + * + * Core options and their values are usually defined in a large static array, + * but they may be generated at runtime based on the loaded game or system state. + * Here are some use cases for that: + * + * @li Selecting a particular file from one of the + * \ref RETRO_ENVIRONMENT_GET_ASSET_DIRECTORY "frontend's" + * \ref RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY "content" + * \ref RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY "directories", + * such as a memory card image or figurine data file. + * @li Excluding options that are not relevant to the current game, + * for cores that define a large number of possible options. + * @li Choosing a default value at runtime for a specific game, + * such as a BIOS file whose region matches that of the loaded content. + * + * @note A guiding principle of libretro's API design is that + * all common interactions (gameplay, menu navigation, etc.) + * should be possible without a keyboard. + * This implies that cores should keep the number of options and values + * as low as possible. + * + * Example entry: + * @code + * { + * "foo_option", + * "Speed hack coprocessor X", + * "Provides increased performance at the expense of reduced accuracy", + * { + * { "false", NULL }, + * { "true", NULL }, + * { "unstable", "Turbo (Unstable)" }, + * { NULL, NULL }, + * }, + * "false" + * } + * @endcode + * + * @param[in] data const struct retro_core_option_definition *. + * Pointer to one or more core option definitions, + * terminated by a \ref retro_core_option_definition whose values are all zero. + * May be \c NULL, in which case the frontend will remove all existing core options. + * The frontend must maintain its own copy of this object, + * including all strings and subobjects. + * @return \c true if this environment call is available. + * + * @see retro_core_option_definition + * @see RETRO_ENVIRONMENT_GET_VARIABLE + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL + */ +#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS 53 + +/** + * A variant of \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS + * that supports internationalization. + * + * @deprecated This environment call has been superseded + * by \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL, + * which supports categorizing options into groups + * (plus translating the groups themselves). + * Only use this environment call to maintain compatibility + * with older cores and frontends. + * + * This should be called instead of \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS + * if the core provides translations for its options. + * General use is largely the same, + * but see \ref retro_core_options_intl for some important details. + * + * @param[in] data const struct retro_core_options_intl *. + * Pointer to a core's option values and their translations. + * @see retro_core_options_intl + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS + */ +#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL 54 + +/** + * Notifies the frontend that it should show or hide the named core option. + * + * Some core options aren't relevant in all scenarios, + * such as a submenu for hardware rendering flags + * when the software renderer is configured. + * This environment call asks the frontend to stop (or start) + * showing the named core option to the player. + * This is only a hint, not a requirement; + * the frontend may ignore this environment call. + * By default, all core options are visible. + * + * @note This environment call must \em only affect a core option's visibility, + * not its functionality or availability. + * \ref RETRO_ENVIRONMENT_GET_VARIABLE "Getting an invisible core option" + * must behave normally. + * + * @param[in] data const struct retro_core_option_display *. + * Pointer to a descriptor for the option that the frontend should show or hide. + * May be \c NULL, in which case the frontend will only return + * whether this environment callback is available. + * @return \c true if this environment call is available, + * even if \c data is \c NULL + * or the specified option doesn't exist. + * @see retro_core_option_display + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_UPDATE_DISPLAY_CALLBACK + */ +#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY 55 + +/** + * Returns the frontend's preferred hardware rendering API. + * Cores should use this information to decide which API to use with \c RETRO_ENVIRONMENT_SET_HW_RENDER. + * @param[out] data retro_hw_context_type *. + * Pointer to the hardware context type. + * Behavior is undefined if \c data is NULL. + * This value will be set even if the environment call returns false, + * unless the frontend doesn't implement it. + * @returns \c true if the environment call is available + * and the frontend is able to use a hardware rendering API besides the one returned. + * If \c false is returned and the core cannot use the preferred rendering API, + * then it should exit or fall back to software rendering. + * @note The returned value does not indicate which API is currently in use. + * For example, the frontend may return \c RETRO_HW_CONTEXT_OPENGL + * while a Direct3D context from a previous session is active; + * this would signal that the frontend's current preference is for OpenGL, + * possibly because the user changed their frontend's video driver while a game is running. + * @see retro_hw_context_type + * @see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE + * @see RETRO_ENVIRONMENT_SET_HW_RENDER + */ +#define RETRO_ENVIRONMENT_GET_PREFERRED_HW_RENDER 56 + +/** + * Returns the minimum version of the disk control interface supported by the frontend. + * + * If this environment call returns \c false or \c data is 0 or greater, + * then cores may use disk control callbacks + * with \c RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE. + * If the reported version is 1 or greater, + * then cores should use \c RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE instead. + * + * @param[out] data unsigned *. + * Pointer to the unsigned integer that the frontend's supported disk control interface version will be stored in. + * Behavior is undefined if \c NULL. + * @return \c true if this environment call is available. + * @see RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE + */ +#define RETRO_ENVIRONMENT_GET_DISK_CONTROL_INTERFACE_VERSION 57 + +/** + * @copybrief RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE + * + * This is intended for multi-disk games that expect the player + * to manually swap disks at certain points in the game. + * This version of the disk control interface provides + * more information about disk images. + * Should be called in \c retro_init. + * + * @param[in] data const struct retro_disk_control_ext_callback *. + * Pointer to the callback functions to use. + * May be \c NULL, in which case the existing disk callback is deregistered. + * @return \c true if this environment call is available, + * even if \c data is \c NULL. + * @see retro_disk_control_ext_callback + */ +#define RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE 58 + +/** + * Returns the version of the message interface supported by the frontend. + * + * A version of 0 indicates that the frontend + * only supports the legacy \c RETRO_ENVIRONMENT_SET_MESSAGE interface. + * A version of 1 indicates that the frontend + * supports \c RETRO_ENVIRONMENT_SET_MESSAGE_EXT as well. + * If this environment call returns \c false, + * the core should behave as if it had returned 0. + * + * @param[out] data unsigned *. + * Pointer to the result returned by the frontend. + * Behavior is undefined if \c NULL. + * @return \c true if this environment call is available. + * @see RETRO_ENVIRONMENT_SET_MESSAGE_EXT + * @see RETRO_ENVIRONMENT_SET_MESSAGE + */ +#define RETRO_ENVIRONMENT_GET_MESSAGE_INTERFACE_VERSION 59 + +/** + * Displays a user-facing message for a short time. + * + * Use this callback to convey important status messages, + * such as errors or the result of long-running operations. + * For trivial messages or logging, use \c RETRO_ENVIRONMENT_GET_LOG_INTERFACE or \c stderr. + * + * This environment call supersedes \c RETRO_ENVIRONMENT_SET_MESSAGE, + * as it provides many more ways to customize + * how a message is presented to the player. + * However, a frontend that supports this environment call + * must still support \c RETRO_ENVIRONMENT_SET_MESSAGE. + * + * @param[in] data const struct retro_message_ext *. + * Pointer to the message to display to the player. + * Behavior is undefined if \c NULL. + * @returns \c true if this environment call is available. + * @see retro_message_ext + * @see RETRO_ENVIRONMENT_GET_MESSAGE_INTERFACE_VERSION + */ +#define RETRO_ENVIRONMENT_SET_MESSAGE_EXT 60 + +/** + * Returns the number of active input devices currently provided by the frontend. + * + * This may change between frames, + * but will remain constant for the duration of each frame. + * + * If this callback returns \c true, + * a core need not poll any input device + * with an index greater than or equal to the returned value. + * + * If callback returns \c false, + * the number of active input devices is unknown. + * In this case, all input devices should be considered active. + * + * @param[out] data unsigned *. + * Pointer to the result returned by the frontend. + * Behavior is undefined if \c NULL. + * @return \c true if this environment call is available. + */ +#define RETRO_ENVIRONMENT_GET_INPUT_MAX_USERS 61 + +/** + * Registers a callback that the frontend can use to notify the core + * of the audio output buffer's occupancy. + * Can be used by a core to attempt frame-skipping to avoid buffer under-runs + * (i.e. "crackling" sounds). + * + * @param[in] data const struct retro_audio_buffer_status_callback *. + * Pointer to the the buffer status callback, + * or \c NULL to unregister any existing callback. + * @return \c true if this environment call is available, + * even if \c data is \c NULL. + * + * @see retro_audio_buffer_status_callback + */ +#define RETRO_ENVIRONMENT_SET_AUDIO_BUFFER_STATUS_CALLBACK 62 + +/** + * Requests a minimum frontend audio latency in milliseconds. + * + * This is a hint; the frontend may assign a different audio latency + * to accommodate hardware limits, + * although it should try to honor requests up to 512ms. + * + * This callback has no effect if the requested latency + * is less than the frontend's current audio latency. + * If value is zero or \c data is \c NULL, + * the frontend should set its default audio latency. + * + * May be used by a core to increase audio latency and + * reduce the risk of buffer under-runs (crackling) + * when performing 'intensive' operations. + * + * A core using RETRO_ENVIRONMENT_SET_AUDIO_BUFFER_STATUS_CALLBACK + * to implement audio-buffer-based frame skipping can get good results + * by setting the audio latency to a high (typically 6x or 8x) + * integer multiple of the expected frame time. + * + * This can only be called from within \c retro_run(). + * + * @warning This environment call may require the frontend to reinitialize its audio system. + * This environment call should be used sparingly. + * If the driver is reinitialized, + * \ref retro_audio_callback_t "all audio callbacks" will be updated + * to target the newly-initialized driver. + * + * @param[in] data const unsigned *. + * Minimum audio latency, in milliseconds. + * @return \c true if this environment call is available, + * even if \c data is \c NULL. + * + * @see RETRO_ENVIRONMENT_SET_AUDIO_BUFFER_STATUS_CALLBACK + */ +#define RETRO_ENVIRONMENT_SET_MINIMUM_AUDIO_LATENCY 63 + +/** + * Allows the core to tell the frontend when it should enable fast-forwarding, + * rather than relying solely on the frontend and user interaction. + * + * Possible use cases include: + * + * \li Temporarily disabling a core's fastforward support + * while investigating a related bug. + * \li Disabling fastforward during netplay sessions, + * or when using an emulated console's network features. + * \li Automatically speeding up the game when in a loading screen + * that cannot be shortened with high-level emulation. + * + * @param[in] data const struct retro_fastforwarding_override *. + * Pointer to the parameters that decide when and how + * the frontend is allowed to enable fast-forward mode. + * May be \c NULL, in which case the frontend will return \c true + * without updating the fastforward state, + * which can be used to detect support for this environment call. + * @return \c true if this environment call is available, + * even if \c data is \c NULL. + * + * @see retro_fastforwarding_override + * @see RETRO_ENVIRONMENT_GET_FASTFORWARDING + */ +#define RETRO_ENVIRONMENT_SET_FASTFORWARDING_OVERRIDE 64 + +#define RETRO_ENVIRONMENT_SET_CONTENT_INFO_OVERRIDE 65 + /* const struct retro_system_content_info_override * -- + * Allows an implementation to override 'global' content + * info parameters reported by retro_get_system_info(). + * Overrides also affect subsystem content info parameters + * set via RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO. + * This function must be called inside retro_set_environment(). + * If callback returns false, content info overrides + * are unsupported by the frontend, and will be ignored. + * If callback returns true, extended game info may be + * retrieved by calling RETRO_ENVIRONMENT_GET_GAME_INFO_EXT + * in retro_load_game() or retro_load_game_special(). + * + * 'data' points to an array of retro_system_content_info_override + * structs terminated by a { NULL, false, false } element. + * If 'data' is NULL, no changes will be made to the frontend; + * a core may therefore pass NULL in order to test whether + * the RETRO_ENVIRONMENT_SET_CONTENT_INFO_OVERRIDE and + * RETRO_ENVIRONMENT_GET_GAME_INFO_EXT callbacks are supported + * by the frontend. + * + * For struct member descriptions, see the definition of + * struct retro_system_content_info_override. + * + * Example: + * + * - struct retro_system_info: + * { + * "My Core", // library_name + * "v1.0", // library_version + * "m3u|md|cue|iso|chd|sms|gg|sg", // valid_extensions + * true, // need_fullpath + * false // block_extract + * } + * + * - Array of struct retro_system_content_info_override: + * { + * { + * "md|sms|gg", // extensions + * false, // need_fullpath + * true // persistent_data + * }, + * { + * "sg", // extensions + * false, // need_fullpath + * false // persistent_data + * }, + * { NULL, false, false } + * } + * + * Result: + * - Files of type m3u, cue, iso, chd will not be + * loaded by the frontend. Frontend will pass a + * valid path to the core, and core will handle + * loading internally + * - Files of type md, sms, gg will be loaded by + * the frontend. A valid memory buffer will be + * passed to the core. This memory buffer will + * remain valid until retro_deinit() returns + * - Files of type sg will be loaded by the frontend. + * A valid memory buffer will be passed to the core. + * This memory buffer will remain valid until + * retro_load_game() (or retro_load_game_special()) + * returns + * + * NOTE: If an extension is listed multiple times in + * an array of retro_system_content_info_override + * structs, only the first instance will be registered + */ + +#define RETRO_ENVIRONMENT_GET_GAME_INFO_EXT 66 + /* const struct retro_game_info_ext ** -- + * Allows an implementation to fetch extended game + * information, providing additional content path + * and memory buffer status details. + * This function may only be called inside + * retro_load_game() or retro_load_game_special(). + * If callback returns false, extended game information + * is unsupported by the frontend. In this case, only + * regular retro_game_info will be available. + * RETRO_ENVIRONMENT_GET_GAME_INFO_EXT is guaranteed + * to return true if RETRO_ENVIRONMENT_SET_CONTENT_INFO_OVERRIDE + * returns true. + * + * 'data' points to an array of retro_game_info_ext structs. + * + * For struct member descriptions, see the definition of + * struct retro_game_info_ext. + * + * - If function is called inside retro_load_game(), + * the retro_game_info_ext array is guaranteed to + * have a size of 1 - i.e. the returned pointer may + * be used to access directly the members of the + * first retro_game_info_ext struct, for example: + * + * struct retro_game_info_ext *game_info_ext; + * if (environ_cb(RETRO_ENVIRONMENT_GET_GAME_INFO_EXT, &game_info_ext)) + * printf("Content Directory: %s\n", game_info_ext->dir); + * + * - If the function is called inside retro_load_game_special(), + * the retro_game_info_ext array is guaranteed to have a + * size equal to the num_info argument passed to + * retro_load_game_special() + */ + +/** + * Defines a set of core options that can be shown and configured by the frontend, + * so that the player may customize their gameplay experience to their liking. + * + * @note This environment call is intended to replace + * \c RETRO_ENVIRONMENT_SET_VARIABLES and \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS, + * and should only be called if \c RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION + * returns an API version of at least 2. + * + * This should be called the first time as early as possible, + * ideally in \c retro_set_environment (but \c retro_load_game is acceptable). + * It may then be called again later to update + * the core's options and their associated values, + * as long as the number of options doesn't change + * from the number given in the first call. + * + * The core can retrieve option values at any time with \c RETRO_ENVIRONMENT_GET_VARIABLE. + * If a saved value for a core option doesn't match the option definition's values, + * the frontend may treat it as incorrect and revert to the default. + * + * Core options and their values are usually defined in a large static array, + * but they may be generated at runtime based on the loaded game or system state. + * Here are some use cases for that: + * + * @li Selecting a particular file from one of the + * \ref RETRO_ENVIRONMENT_GET_ASSET_DIRECTORY "frontend's" + * \ref RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY "content" + * \ref RETRO_ENVIRONMENT_GET_CORE_ASSETS_DIRECTORY "directories", + * such as a memory card image or figurine data file. + * @li Excluding options that are not relevant to the current game, + * for cores that define a large number of possible options. + * @li Choosing a default value at runtime for a specific game, + * such as a BIOS file whose region matches that of the loaded content. + * + * @note A guiding principle of libretro's API design is that + * all common interactions (gameplay, menu navigation, etc.) + * should be possible without a keyboard. + * This implies that cores should keep the number of options and values + * as low as possible. + * + * @param[in] data const struct retro_core_options_v2 *. + * Pointer to a core's options and their associated categories. + * May be \c NULL, in which case the frontend will remove all existing core options. + * The frontend must maintain its own copy of this object, + * including all strings and subobjects. + * @return \c true if this environment call is available + * and the frontend supports categories. + * Note that this environment call is guaranteed to successfully register + * the provided core options, + * so the return value does not indicate success or failure. + * + * @see retro_core_options_v2 + * @see retro_core_option_v2_category + * @see retro_core_option_v2_definition + * @see RETRO_ENVIRONMENT_GET_VARIABLE + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL + */ +#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 67 + +/** + * A variant of \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + * that supports internationalization. + * + * This should be called instead of \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + * if the core provides translations for its options. + * General use is largely the same, + * but see \ref retro_core_options_v2_intl for some important details. + * + * @param[in] data const struct retro_core_options_v2_intl *. + * Pointer to a core's option values and categories, + * plus a translation for each option and category. + * @see retro_core_options_v2_intl + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + */ +#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL 68 + +/** + * Registers a callback that the frontend can use + * to notify the core that at least one core option + * should be made hidden or visible. + * Allows a frontend to signal that a core must update + * the visibility of any dynamically hidden core options, + * and enables the frontend to detect visibility changes. + * Used by the frontend to update the menu display status + * of core options without requiring a call of retro_run(). + * Must be called in retro_set_environment(). + * + * @param[in] data const struct retro_core_options_update_display_callback *. + * The callback that the frontend should use. + * May be \c NULL, in which case the frontend will unset any existing callback. + * Can be used to query visibility support. + * @return \c true if this environment call is available, + * even if \c data is \c NULL. + * @see retro_core_options_update_display_callback + */ +#define RETRO_ENVIRONMENT_SET_CORE_OPTIONS_UPDATE_DISPLAY_CALLBACK 69 + +/** + * Forcibly sets a core option's value. + * + * After changing a core option value with this callback, + * it will be reflected in the frontend + * and \ref RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE will return \c true. + * \ref retro_variable::key must match + * a \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 "previously-set core option", + * and \ref retro_variable::value must match one of its defined values. + * + * Possible use cases include: + * + * @li Allowing the player to set certain core options + * without entering the frontend's option menu, + * using an in-core hotkey. + * @li Adjusting invalid combinations of settings. + * @li Migrating settings from older releases of a core. + * + * @param[in] data const struct retro_variable *. + * Pointer to a single option that the core is changing. + * May be \c NULL, in which case the frontend will return \c true + * to indicate that this environment call is available. + * @return \c true if this environment call is available + * and the option named by \c key was successfully + * set to the given \c value. + * \c false if the \c key or \c value fields are \c NULL, empty, + * or don't match a previously set option. + * + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + * @see RETRO_ENVIRONMENT_GET_VARIABLE + * @see RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE + */ +#define RETRO_ENVIRONMENT_SET_VARIABLE 70 + +#define RETRO_ENVIRONMENT_GET_THROTTLE_STATE (71 | RETRO_ENVIRONMENT_EXPERIMENTAL) + /* struct retro_throttle_state * -- + * Allows an implementation to get details on the actual rate + * the frontend is attempting to call retro_run(). + */ + +/** + * Returns information about how the frontend will use savestates. + * + * @param[out] data retro_savestate_context *. + * Pointer to the current savestate context. + * May be \c NULL, in which case the environment call + * will return \c true to indicate its availability. + * @returns \c true if the environment call is available, + * even if \c data is \c NULL. + * @see retro_savestate_context + */ +#define RETRO_ENVIRONMENT_GET_SAVESTATE_CONTEXT (72 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Before calling \c SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE, will query which interface is supported. + * + * Frontend looks at \c retro_hw_render_interface_type and returns the maximum supported + * context negotiation interface version. If the \c retro_hw_render_interface_type is not + * supported or recognized by the frontend, a version of 0 must be returned in + * \c retro_hw_render_interface's \c interface_version and \c true is returned by frontend. + * + * If this environment call returns true with a \c interface_version greater than 0, + * a core can always use a negotiation interface version larger than what the frontend returns, + * but only earlier versions of the interface will be used by the frontend. + * + * A frontend must not reject a negotiation interface version that is larger than what the + * frontend supports. Instead, the frontend will use the older entry points that it recognizes. + * If this is incompatible with a particular core's requirements, it can error out early. + * + * @note Regarding backwards compatibility, this environment call was introduced after Vulkan v1 + * context negotiation. If this environment call is not supported by frontend, i.e. the environment + * call returns \c false , only Vulkan v1 context negotiation is supported (if Vulkan HW rendering + * is supported at all). If a core uses Vulkan negotiation interface with version > 1, negotiation + * may fail unexpectedly. All future updates to the context negotiation interface implies that + * frontend must support this environment call to query support. + * + * @param[out] data struct retro_hw_render_context_negotiation_interface *. + * @return \c true if the environment call is available. + * @see SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE + * @see retro_hw_render_interface_type + * @see retro_hw_render_context_negotiation_interface + */ +#define RETRO_ENVIRONMENT_GET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_SUPPORT (73 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Asks the frontend whether JIT compilation can be used. + * Primarily used by iOS and tvOS. + * @param[out] data bool *. + * Set to \c true if the frontend has verified that JIT compilation is possible. + * @return \c true if the environment call is available. + */ +#define RETRO_ENVIRONMENT_GET_JIT_CAPABLE 74 + +/** + * Returns an interface that the core can use to receive microphone input. + * + * @param[out] data retro_microphone_interface *. + * Pointer to the microphone interface. + * @return \true if microphone support is available, + * even if no microphones are plugged in. + * \c false if microphone support is disabled unavailable, + * or if \c data is \c NULL. + * @see retro_microphone_interface + */ +#define RETRO_ENVIRONMENT_GET_MICROPHONE_INTERFACE (75 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/* Environment 76 was an obsolete version of RETRO_ENVIRONMENT_SET_NETPACKET_INTERFACE. +* It was not used by any known core at the time, and was removed from the API. */ + +/** + * Returns the device's current power state as reported by the frontend. + * + * This is useful for emulating the battery level in handheld consoles, + * or for reducing power consumption when on battery power. + * + * @note This environment call describes the power state for the entire device, + * not for individual peripherals like controllers. + * + * @param[out] data . + * Indicates whether the frontend can provide this information, even if the parameter + * is \c NULL. If the frontend does not support this functionality, then the provided + * argument will remain unchanged. + * @return \c true if the environment call is available. + * @see retro_device_power + */ +#define RETRO_ENVIRONMENT_GET_DEVICE_POWER (77 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +#define RETRO_ENVIRONMENT_SET_NETPACKET_INTERFACE 78 + /* const struct retro_netpacket_callback * -- + * When set, a core gains control over network packets sent and + * received during a multiplayer session. This can be used to + * emulate multiplayer games that were originally played on two + * or more separate consoles or computers connected together. + * + * The frontend will take care of connecting players together, + * and the core only needs to send the actual data as needed for + * the emulation, while handshake and connection management happen + * in the background. + * + * When two or more players are connected and this interface has + * been set, time manipulation features (such as pausing, slow motion, + * fast forward, rewinding, save state loading, etc.) are disabled to + * avoid interrupting communication. + * + * Should be set in either retro_init or retro_load_game, but not both. + * + * When not set, a frontend may use state serialization-based + * multiplayer, where a deterministic core supporting multiple + * input devices does not need to take any action on its own. + */ + +/** + * Returns the device's current power state as reported by the frontend. + * This is useful for emulating the battery level in handheld consoles, + * or for reducing power consumption when on battery power. + * + * The return value indicates whether the frontend can provide this information, + * even if the parameter is \c NULL. + * + * If the frontend does not support this functionality, + * then the provided argument will remain unchanged. + * @param[out] data retro_device_power *. + * Pointer to the information that the frontend returns about its power state. + * May be \c NULL. + * @return \c true if the environment call is available, + * even if \c data is \c NULL. + * @see retro_device_power + * @note This environment call describes the power state for the entire device, + * not for individual peripherals like controllers. +*/ +#define RETRO_ENVIRONMENT_GET_DEVICE_POWER (77 | RETRO_ENVIRONMENT_EXPERIMENTAL) + +/** + * Returns the "playlist" directory of the frontend. + * + * This directory can be used to store core generated playlists, in case + * this internal functionality is available (e.g. internal core game detection + * engine). + * + * @param[out] data const char **. + * May be \c NULL. If so, no such directory is defined, and it's up to the + * implementation to find a suitable directory. + * @return \c true if the environment call is available. + */ +#define RETRO_ENVIRONMENT_GET_PLAYLIST_DIRECTORY 79 + +/**@}*/ + +/** + * @defgroup GET_VFS_INTERFACE File System Interface + * @brief File system functionality. + * + * @section File Paths + * File paths passed to all libretro filesystem APIs shall be well formed UNIX-style, + * using "/" (unquoted forward slash) as the directory separator + * regardless of the platform's native separator. + * + * Paths shall also include at least one forward slash + * (e.g. use "./game.bin" instead of "game.bin"). + * + * Other than the directory separator, cores shall not make assumptions about path format. + * The following paths are all valid: + * @li \c C:/path/game.bin + * @li \c http://example.com/game.bin + * @li \c #game/game.bin + * @li \c ./game.bin + * + * Cores may replace the basename or remove path components from the end, and/or add new components; + * however, cores shall not append "./", "../" or multiple consecutive forward slashes ("//") to paths they request from the front end. + * + * The frontend is encouraged to do the best it can when given an ill-formed path, + * but it is allowed to give up. + * + * Frontends are encouraged, but not required, to support native file system paths + * (including replacing the directory separator, if applicable). + * + * Cores are allowed to try using them, but must remain functional if the frontend rejects such requests. + * + * Cores are encouraged to use the libretro-common filestream functions for file I/O, + * as they seamlessly integrate with VFS, + * deal with directory separator replacement as appropriate + * and provide platform-specific fallbacks + * in cases where front ends do not provide their own VFS interface. + * + * @see RETRO_ENVIRONMENT_GET_VFS_INTERFACE + * @see retro_vfs_interface_info + * @see file_path + * @see retro_dirent + * @see file_stream + * + * @{ + */ + +/** + * Opaque file handle. + * @since VFS API v1 + */ +struct retro_vfs_file_handle; + +/** + * Opaque directory handle. + * @since VFS API v3 + */ +struct retro_vfs_dir_handle; + +/** @defgroup RETRO_VFS_FILE_ACCESS File Access Flags + * File access flags. + * @since VFS API v1 + * @{ + */ + +/** Opens a file for read-only access. */ +#define RETRO_VFS_FILE_ACCESS_READ (1 << 0) + +/** + * Opens a file for write-only access. + * Any existing file at this path will be discarded and overwritten + * unless \c RETRO_VFS_FILE_ACCESS_UPDATE_EXISTING is also specified. + */ +#define RETRO_VFS_FILE_ACCESS_WRITE (1 << 1) + +/** + * Opens a file for reading and writing. + * Any existing file at this path will be discarded and overwritten + * unless \c RETRO_VFS_FILE_ACCESS_UPDATE_EXISTING is also specified. + */ +#define RETRO_VFS_FILE_ACCESS_READ_WRITE (RETRO_VFS_FILE_ACCESS_READ | RETRO_VFS_FILE_ACCESS_WRITE) + +/** + * Opens a file without discarding its existing contents. + * Only meaningful if \c RETRO_VFS_FILE_ACCESS_WRITE is specified. + */ +#define RETRO_VFS_FILE_ACCESS_UPDATE_EXISTING (1 << 2) /* Prevents discarding content of existing files opened for writing */ + +/** @} */ + +/** @defgroup RETRO_VFS_FILE_ACCESS_HINT File Access Hints + * + * Hints to the frontend for how a file will be accessed. + * The VFS implementation may use these to optimize performance, + * react to external interference (such as concurrent writes), + * or it may ignore them entirely. + * + * Hint flags do not change the behavior of each VFS function + * unless otherwise noted. + * @{ + */ + +/** No particular hints are given. */ +#define RETRO_VFS_FILE_ACCESS_HINT_NONE (0) + +/** + * Indicates that the file will be accessed frequently. + * + * The frontend should cache it or map it into memory. + */ +#define RETRO_VFS_FILE_ACCESS_HINT_FREQUENT_ACCESS (1 << 0) + +/** @} */ + +/** @defgroup RETRO_VFS_SEEK_POSITION File Seek Positions + * File access flags and hints. + * @{ + */ + +/** + * Indicates a seek relative to the start of the file. + */ +#define RETRO_VFS_SEEK_POSITION_START 0 + +/** + * Indicates a seek relative to the current stream position. + */ +#define RETRO_VFS_SEEK_POSITION_CURRENT 1 + +/** + * Indicates a seek relative to the end of the file. + * @note The offset passed to \c retro_vfs_seek_t should be negative. + */ +#define RETRO_VFS_SEEK_POSITION_END 2 + +/** @} */ + +/** @defgroup RETRO_VFS_STAT File Status Flags + * File stat flags. + * @see retro_vfs_stat_t + * @since VFS API v3 + * @{ + */ + +/** Indicates that the given path refers to a valid file. */ +#define RETRO_VFS_STAT_IS_VALID (1 << 0) + +/** Indicates that the given path refers to a directory. */ +#define RETRO_VFS_STAT_IS_DIRECTORY (1 << 1) + +/** + * Indicates that the given path refers to a character special file, + * such as \c /dev/null. + */ +#define RETRO_VFS_STAT_IS_CHARACTER_SPECIAL (1 << 2) + +/** @} */ + +/** + * Returns the path that was used to open this file. + * + * @param stream The opened file handle to get the path of. + * Behavior is undefined if \c NULL or closed. + * @return The path that was used to open \c stream. + * The string is owned by \c stream and must not be modified. + * @since VFS API v1 + * @see filestream_get_path + */ +typedef const char *(RETRO_CALLCONV *retro_vfs_get_path_t)(struct retro_vfs_file_handle *stream); + +/** + * Open a file for reading or writing. + * + * @param path The path to open. + * @param mode A bitwise combination of \c RETRO_VFS_FILE_ACCESS flags. + * At a minimum, one of \c RETRO_VFS_FILE_ACCESS_READ or \c RETRO_VFS_FILE_ACCESS_WRITE must be specified. + * @param hints A bitwise combination of \c RETRO_VFS_FILE_ACCESS_HINT flags. + * @return A handle to the opened file, + * or \c NULL upon failure. + * Note that this will return \c NULL if \c path names a directory. + * The returned file handle must be closed with \c retro_vfs_close_t. + * @since VFS API v1 + * @see File Paths + * @see RETRO_VFS_FILE_ACCESS + * @see RETRO_VFS_FILE_ACCESS_HINT + * @see retro_vfs_close_t + * @see filestream_open + */ +typedef struct retro_vfs_file_handle *(RETRO_CALLCONV *retro_vfs_open_t)(const char *path, unsigned mode, unsigned hints); + +/** + * Close the file and release its resources. + * All files returned by \c retro_vfs_open_t must be closed with this function. + * + * @param stream The file handle to close. + * Behavior is undefined if already closed. + * Upon completion of this function, \c stream is no longer valid + * (even if it returns failure). + * @return 0 on success, -1 on failure or if \c stream is \c NULL. + * @see retro_vfs_open_t + * @see filestream_close + * @since VFS API v1 + */ +typedef int (RETRO_CALLCONV *retro_vfs_close_t)(struct retro_vfs_file_handle *stream); + +/** + * Return the size of the file in bytes. + * + * @param stream The file to query the size of. + * @return Size of the file in bytes, or -1 if there was an error. + * @see filestream_get_size + * @since VFS API v1 + */ +typedef int64_t (RETRO_CALLCONV *retro_vfs_size_t)(struct retro_vfs_file_handle *stream); + +/** + * Set the file's length. + * + * @param stream The file whose length will be adjusted. + * @param length The new length of the file, in bytes. + * If shorter than the original length, the extra bytes will be discarded. + * If longer, the file's padding is unspecified (and likely platform-dependent). + * @return 0 on success, + * -1 on failure. + * @see filestream_truncate + * @since VFS API v2 + */ +typedef int64_t (RETRO_CALLCONV *retro_vfs_truncate_t)(struct retro_vfs_file_handle *stream, int64_t length); + +/** + * Gets the given file's current read/write position. + * This position is advanced with each call to \c retro_vfs_read_t or \c retro_vfs_write_t. + * + * @param stream The file to query the position of. + * @return The current stream position in bytes + * or -1 if there was an error. + * @see filestream_tell + * @since VFS API v1 + */ +typedef int64_t (RETRO_CALLCONV *retro_vfs_tell_t)(struct retro_vfs_file_handle *stream); + +/** + * Sets the given file handle's current read/write position. + * + * @param stream The file to set the position of. + * @param offset The new position, in bytes. + * @param seek_position The position to seek from. + * @return The new position, + * or -1 if there was an error. + * @since VFS API v1 + * @see File Seek Positions + * @see filestream_seek + */ +typedef int64_t (RETRO_CALLCONV *retro_vfs_seek_t)(struct retro_vfs_file_handle *stream, int64_t offset, int seek_position); + +/** + * Read data from a file, if it was opened for reading. + * + * @param stream The file to read from. + * @param s The buffer to read into. + * @param len The number of bytes to read. + * The buffer pointed to by \c s must be this large. + * @return The number of bytes read, + * or -1 if there was an error. + * @since VFS API v1 + * @see filestream_read + */ +typedef int64_t (RETRO_CALLCONV *retro_vfs_read_t)(struct retro_vfs_file_handle *stream, void *s, uint64_t len); + +/** + * Write data to a file, if it was opened for writing. + * + * @param stream The file handle to write to. + * @param s The buffer to write from. + * @param len The number of bytes to write. + * The buffer pointed to by \c s must be this large. + * @return The number of bytes written, + * or -1 if there was an error. + * @since VFS API v1 + * @see filestream_write + */ +typedef int64_t (RETRO_CALLCONV *retro_vfs_write_t)(struct retro_vfs_file_handle *stream, const void *s, uint64_t len); + +/** + * Flush pending writes to the file, if applicable. + * + * This does not mean that the changes will be immediately persisted to disk; + * that may be scheduled for later, depending on the platform. + * + * @param stream The file handle to flush. + * @return 0 on success, -1 on failure. + * @since VFS API v1 + * @see filestream_flush + */ +typedef int (RETRO_CALLCONV *retro_vfs_flush_t)(struct retro_vfs_file_handle *stream); + +/** + * Deletes the file at the given path. + * + * @param path The path to the file that will be deleted. + * @return 0 on success, -1 on failure. + * @see filestream_delete + * @since VFS API v1 + */ +typedef int (RETRO_CALLCONV *retro_vfs_remove_t)(const char *path); + +/** + * Rename the specified file. + * + * @param old_path Path to an existing file. + * @param new_path The destination path. + * Must not name an existing file. + * @return 0 on success, -1 on failure + * @see filestream_rename + * @since VFS API v1 + */ +typedef int (RETRO_CALLCONV *retro_vfs_rename_t)(const char *old_path, const char *new_path); + +/** + * Gets information about the given file. + * + * @param path The path to the file to query. + * @param[out] size The reported size of the file in bytes. + * May be \c NULL, in which case this value is ignored. + * @return A bitmask of \c RETRO_VFS_STAT flags, + * or 0 if \c path doesn't refer to a valid file. + * @see path_stat + * @see path_get_size + * @see RETRO_VFS_STAT + * @since VFS API v3 + */ +typedef int (RETRO_CALLCONV *retro_vfs_stat_t)(const char *path, int32_t *size); + +/** + * Creates a directory at the given path. + * + * @param dir The desired location of the new directory. + * @return 0 if the directory was created, + * -2 if the directory already exists, + * or -1 if some other error occurred. + * @see path_mkdir + * @since VFS API v3 + */ +typedef int (RETRO_CALLCONV *retro_vfs_mkdir_t)(const char *dir); + +/** + * Opens a handle to a directory so its contents can be inspected. + * + * @param dir The path to the directory to open. + * Must be an existing directory. + * @param include_hidden Whether to include hidden files in the directory listing. + * The exact semantics of this flag will depend on the platform. + * @return A handle to the opened directory, + * or \c NULL if there was an error. + * @see retro_opendir + * @since VFS API v3 + */ +typedef struct retro_vfs_dir_handle *(RETRO_CALLCONV *retro_vfs_opendir_t)(const char *dir, bool include_hidden); + +/** + * Gets the next dirent ("directory entry") + * within the given directory. + * + * @param[in,out] dirstream The directory to read from. + * Updated to point to the next file, directory, or other path. + * @return \c true when the next dirent was retrieved, + * \c false if there are no more dirents to read. + * @note This API iterates over all files and directories within \c dirstream. + * Remember to check what the type of the current dirent is. + * @note This function does not recurse, + * i.e. it does not return the contents of subdirectories. + * @note This may include "." and ".." on Unix-like platforms. + * @see retro_readdir + * @see retro_vfs_dirent_is_dir_t + * @since VFS API v3 + */ +typedef bool (RETRO_CALLCONV *retro_vfs_readdir_t)(struct retro_vfs_dir_handle *dirstream); + +/** + * Gets the filename of the current dirent. + * + * The returned string pointer is valid + * until the next call to \c retro_vfs_readdir_t or \c retro_vfs_closedir_t. + * + * @param dirstream The directory to read from. + * @return The current dirent's name, + * or \c NULL if there was an error. + * @note This function only returns the file's \em name, + * not a complete path to it. + * @see retro_dirent_get_name + * @since VFS API v3 + */ +typedef const char *(RETRO_CALLCONV *retro_vfs_dirent_get_name_t)(struct retro_vfs_dir_handle *dirstream); + +/** + * Checks whether the current dirent names a directory. + * + * @param dirstream The directory to read from. + * @return \c true if \c dirstream's current dirent points to a directory, + * \c false if not or if there was an error. + * @see retro_dirent_is_dir + * @since VFS API v3 + */ +typedef bool (RETRO_CALLCONV *retro_vfs_dirent_is_dir_t)(struct retro_vfs_dir_handle *dirstream); + +/** + * Closes the given directory and release its resources. + * + * Must be called on any \c retro_vfs_dir_handle returned by \c retro_vfs_open_t. + * + * @param dirstream The directory to close. + * When this function returns (even failure), + * \c dirstream will no longer be valid and must not be used. + * @return 0 on success, -1 on failure. + * @see retro_closedir + * @since VFS API v3 + */ +typedef int (RETRO_CALLCONV *retro_vfs_closedir_t)(struct retro_vfs_dir_handle *dirstream); + +/** + * File system interface exposed by the frontend. + * + * @see dirent_vfs_init + * @see filestream_vfs_init + * @see path_vfs_init + * @see RETRO_ENVIRONMENT_GET_VFS_INTERFACE + */ +struct retro_vfs_interface +{ + /* VFS API v1 */ + /** @copydoc retro_vfs_get_path_t */ + retro_vfs_get_path_t get_path; + + /** @copydoc retro_vfs_open_t */ + retro_vfs_open_t open; + + /** @copydoc retro_vfs_close_t */ + retro_vfs_close_t close; + + /** @copydoc retro_vfs_size_t */ + retro_vfs_size_t size; + + /** @copydoc retro_vfs_tell_t */ + retro_vfs_tell_t tell; + + /** @copydoc retro_vfs_seek_t */ + retro_vfs_seek_t seek; + + /** @copydoc retro_vfs_read_t */ + retro_vfs_read_t read; + + /** @copydoc retro_vfs_write_t */ + retro_vfs_write_t write; + + /** @copydoc retro_vfs_flush_t */ + retro_vfs_flush_t flush; + + /** @copydoc retro_vfs_remove_t */ + retro_vfs_remove_t remove; + + /** @copydoc retro_vfs_rename_t */ + retro_vfs_rename_t rename; + /* VFS API v2 */ + + /** @copydoc retro_vfs_truncate_t */ + retro_vfs_truncate_t truncate; + /* VFS API v3 */ + + /** @copydoc retro_vfs_stat_t */ + retro_vfs_stat_t stat; + + /** @copydoc retro_vfs_mkdir_t */ + retro_vfs_mkdir_t mkdir; + + /** @copydoc retro_vfs_opendir_t */ + retro_vfs_opendir_t opendir; + + /** @copydoc retro_vfs_readdir_t */ + retro_vfs_readdir_t readdir; + + /** @copydoc retro_vfs_dirent_get_name_t */ + retro_vfs_dirent_get_name_t dirent_get_name; + + /** @copydoc retro_vfs_dirent_is_dir_t */ + retro_vfs_dirent_is_dir_t dirent_is_dir; + + /** @copydoc retro_vfs_closedir_t */ + retro_vfs_closedir_t closedir; +}; + +/** + * Represents a request by the core for the frontend's file system interface, + * as well as the interface itself returned by the frontend. + * + * You do not need to use these functions directly; + * you may pass this struct to \c dirent_vfs_init, + * \c filestream_vfs_init, or \c path_vfs_init + * so that you can use the wrappers provided by these modules. + * + * @see dirent_vfs_init + * @see filestream_vfs_init + * @see path_vfs_init + * @see RETRO_ENVIRONMENT_GET_VFS_INTERFACE + */ +struct retro_vfs_interface_info +{ + /** + * The minimum version of the VFS API that the core requires. + * libretro-common's wrapper API initializers will check this value as well. + * + * Set to the core's desired VFS version when requesting an interface, + * and set by the frontend to indicate its actual API version. + * + * If the core asks for a newer VFS API version than the frontend supports, + * the frontend must return \c false within the \c RETRO_ENVIRONMENT_GET_VFS_INTERFACE call. + * @since VFS API v1 + */ + uint32_t required_interface_version; + + /** + * Set by the frontend. + * The frontend will set this to the VFS interface it provides. + * + * The interface is owned by the frontend + * and must not be modified or freed by the core. + * @since VFS API v1 */ + struct retro_vfs_interface *iface; +}; + +/** @} */ + +/** @defgroup GET_HW_RENDER_INTERFACE Hardware Rendering Interface + * @{ + */ + +/** + * Describes the hardware rendering API supported by + * a particular subtype of \c retro_hw_render_interface. + * + * Not every rendering API supported by libretro has its own interface, + * or even needs one. + * + * @see RETRO_ENVIRONMENT_SET_HW_RENDER + * @see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE + */ +enum retro_hw_render_interface_type +{ + /** + * Indicates a \c retro_hw_render_interface for Vulkan. + * @see retro_hw_render_interface_vulkan + */ + RETRO_HW_RENDER_INTERFACE_VULKAN = 0, + + /** Indicates a \c retro_hw_render_interface for Direct3D 9. */ + RETRO_HW_RENDER_INTERFACE_D3D9 = 1, + + /** Indicates a \c retro_hw_render_interface for Direct3D 10. */ + RETRO_HW_RENDER_INTERFACE_D3D10 = 2, + + /** + * Indicates a \c retro_hw_render_interface for Direct3D 11. + * @see retro_hw_render_interface_d3d11 + */ + RETRO_HW_RENDER_INTERFACE_D3D11 = 3, + + /** + * Indicates a \c retro_hw_render_interface for Direct3D 12. + * @see retro_hw_render_interface_d3d12 + */ + RETRO_HW_RENDER_INTERFACE_D3D12 = 4, + + /** + * Indicates a \c retro_hw_render_interface for + * the PlayStation's 2 PSKit API. + * @see retro_hw_render_interface_gskit_ps2 + */ + RETRO_HW_RENDER_INTERFACE_GSKIT_PS2 = 5, + + /** @private Defined to ensure sizeof(retro_hw_render_interface_type) == sizeof(int). + * Do not use. */ + RETRO_HW_RENDER_INTERFACE_DUMMY = INT_MAX +}; + +/** + * Base render interface type. + * All \c retro_hw_render_interface implementations + * will start with these two fields set to particular values. + * + * @see retro_hw_render_interface_type + * @see RETRO_ENVIRONMENT_SET_HW_RENDER + * @see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE + */ +struct retro_hw_render_interface +{ + /** + * Denotes the particular rendering API that this interface is for. + * Each interface requires this field to be set to a particular value. + * Use it to cast this interface to the appropriate pointer. + */ + enum retro_hw_render_interface_type interface_type; + + /** + * The version of this rendering interface. + * @note This is not related to the version of the API itself. + */ + unsigned interface_version; +}; + +/** @} */ + +/** + * @defgroup GET_LED_INTERFACE LED Interface + * @{ + */ + +/** @copydoc retro_led_interface::set_led_state */ +typedef void (RETRO_CALLCONV *retro_set_led_state_t)(int led, int state); + +/** + * Interface that the core can use to set the state of available LEDs. + * @see RETRO_ENVIRONMENT_GET_LED_INTERFACE + */ +struct retro_led_interface +{ + /** + * Sets the state of an LED. + * + * @param led The LED to set the state of. + * @param state The state to set the LED to. + * \c true to enable, \c false to disable. + */ + retro_set_led_state_t set_led_state; +}; + +/** @} */ + +/** @defgroup GET_AUDIO_VIDEO_ENABLE Skipped A/V Steps + * @{ + */ + +/** + * Flags that define A/V steps that the core may skip for this frame. + * + * @see RETRO_ENVIRONMENT_GET_AUDIO_VIDEO_ENABLE + */ +enum retro_av_enable_flags +{ + /** + * If set, the core should render video output with \c retro_video_refresh_t as normal. + * + * Otherwise, the frontend will discard any video data received this frame, + * including frames presented via hardware acceleration. + * \c retro_video_refresh_t will do nothing. + * + * @note After running the frame, the video output of the next frame + * should be no different than if video was enabled, + * and saving and loading state should have no issues. + * This implies that the emulated console's graphics pipeline state + * should not be affected by this flag. + * + * @note If emulating a platform that supports display capture + * (i.e. reading its own VRAM), + * the core may not be able to completely skip rendering, + * as the VRAM is part of the graphics pipeline's state. + */ + RETRO_AV_ENABLE_VIDEO = (1 << 0), + + /** + * If set, the core should render audio output + * with \c retro_audio_sample_t or \c retro_audio_sample_batch_t as normal. + * + * Otherwise, the frontend will discard any audio data received this frame. + * The core should skip audio rendering if possible. + * + * @note After running the frame, the audio output of the next frame + * should be no different than if audio was enabled, + * and saving and loading state should have no issues. + * This implies that the emulated console's audio pipeline state + * should not be affected by this flag. + */ + RETRO_AV_ENABLE_AUDIO = (1 << 1), + + /** + * If set, indicates that any savestates taken this frame + * are guaranteed to be created by the same binary that will load them, + * and will not be written to or read from the disk. + * + * The core may use these guarantees to: + * + * @li Assume that loading state will succeed. + * @li Update its memory buffers in-place if possible. + * @li Skip clearing memory. + * @li Skip resetting the system. + * @li Skip validation steps. + * + * @deprecated Use \c RETRO_ENVIRONMENT_GET_SAVESTATE_CONTEXT instead, + * except for compatibility purposes. + */ + RETRO_AV_ENABLE_FAST_SAVESTATES = (1 << 2), + + /** + * If set, indicates that the frontend will never need audio from the core. + * Used by a frontend for implementing runahead via a secondary core instance. + * + * The core may stop synthesizing audio if it can do so + * without compromising emulation accuracy. + * + * Audio output for the next frame does not matter, + * and the frontend will never need an accurate audio state in the future. + * + * State will never be saved while this flag is set. + */ + RETRO_AV_ENABLE_HARD_DISABLE_AUDIO = (1 << 3), + + /** + * @private Defined to ensure sizeof(retro_av_enable_flags) == sizeof(int). + * Do not use. + */ + RETRO_AV_ENABLE_DUMMY = INT_MAX +}; + +/** @} */ + +/** + * @defgroup GET_MIDI_INTERFACE MIDI Interface + * @{ + */ + +/** @copydoc retro_midi_interface::input_enabled */ +typedef bool (RETRO_CALLCONV *retro_midi_input_enabled_t)(void); + +/** @copydoc retro_midi_interface::output_enabled */ +typedef bool (RETRO_CALLCONV *retro_midi_output_enabled_t)(void); + +/** @copydoc retro_midi_interface::read */ +typedef bool (RETRO_CALLCONV *retro_midi_read_t)(uint8_t *byte); + +/** @copydoc retro_midi_interface::write */ +typedef bool (RETRO_CALLCONV *retro_midi_write_t)(uint8_t byte, uint32_t delta_time); + +/** @copydoc retro_midi_interface::flush */ +typedef bool (RETRO_CALLCONV *retro_midi_flush_t)(void); + +/** + * Interface that the core can use for raw MIDI I/O. + */ +struct retro_midi_interface +{ + /** + * Retrieves the current state of MIDI input. + * + * @return \c true if MIDI input is enabled. + */ + retro_midi_input_enabled_t input_enabled; + + /** + * Retrieves the current state of MIDI output. + * @return \c true if MIDI output is enabled. + */ + retro_midi_output_enabled_t output_enabled; + + /** + * Reads a byte from the MIDI input stream. + * + * @param[out] byte The byte received from the input stream. + * @return \c true if a byte was read, + * \c false if MIDI input is disabled or \c byte is \c NULL. + */ + retro_midi_read_t read; + + /** + * Writes a byte to the output stream. + * + * @param byte The byte to write to the output stream. + * @param delta_time Time since the previous write, in microseconds. + * @return \c true if c\ byte was written, false otherwise. + */ + retro_midi_write_t write; + + /** + * Flushes previously-written data. + * + * @return \c true if successful. + */ + retro_midi_flush_t flush; +}; + +/** @} */ + +/** @defgroup SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE Render Context Negotiation + * @{ + */ + +/** + * Describes the hardware rendering API used by + * a particular subtype of \c retro_hw_render_context_negotiation_interface. + * + * Not every rendering API supported by libretro has a context negotiation interface, + * or even needs one. + * + * @see RETRO_ENVIRONMENT_SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE + * @see RETRO_ENVIRONMENT_SET_HW_RENDER + * @see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE + */ +enum retro_hw_render_context_negotiation_interface_type +{ + /** + * Denotes a context negotiation interface for Vulkan. + * @see retro_hw_render_context_negotiation_interface_vulkan + */ + RETRO_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_VULKAN = 0, + + /** + * @private Defined to ensure sizeof(retro_hw_render_context_negotiation_interface_type) == sizeof(int). + * Do not use. + */ + RETRO_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_DUMMY = INT_MAX +}; + +/** + * Base context negotiation interface type. + * All \c retro_hw_render_context_negotiation_interface implementations + * will start with these two fields set to particular values. + * + * @see retro_hw_render_interface_type + * @see RETRO_ENVIRONMENT_SET_HW_RENDER + * @see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE + * @see RETRO_ENVIRONMENT_SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE + */ +struct retro_hw_render_context_negotiation_interface +{ + /** + * Denotes the particular rendering API that this interface is for. + * Each interface requires this field to be set to a particular value. + * Use it to cast this interface to the appropriate pointer. + */ + enum retro_hw_render_context_negotiation_interface_type interface_type; + + /** + * The version of this negotiation interface. + * @note This is not related to the version of the API itself. + */ + unsigned interface_version; +}; + +/** @} */ + +/** @defgroup RETRO_SERIALIZATION_QUIRK Serialization Quirks + * @{ + */ + +/** + * Indicates that serialized state is incomplete in some way. + * + * Set if serialization is usable for the common case of saving and loading game state, + * but should not be relied upon for frame-sensitive frontend features + * such as netplay or rerecording. + */ +#define RETRO_SERIALIZATION_QUIRK_INCOMPLETE (1 << 0) + +/** + * Indicates that core must spend some time initializing before serialization can be done. + * + * \c retro_serialize(), \c retro_unserialize(), and \c retro_serialize_size() will initially fail. + */ +#define RETRO_SERIALIZATION_QUIRK_MUST_INITIALIZE (1 << 1) + +/** Set by the core to indicate that serialization size may change within a session. */ +#define RETRO_SERIALIZATION_QUIRK_CORE_VARIABLE_SIZE (1 << 2) + +/** Set by the frontend to acknowledge that it supports variable-sized states. */ +#define RETRO_SERIALIZATION_QUIRK_FRONT_VARIABLE_SIZE (1 << 3) + +/** Serialized state can only be loaded during the same session. */ +#define RETRO_SERIALIZATION_QUIRK_SINGLE_SESSION (1 << 4) + +/** + * Serialized state cannot be loaded on an architecture + * with a different endianness from the one it was saved on. + */ +#define RETRO_SERIALIZATION_QUIRK_ENDIAN_DEPENDENT (1 << 5) + +/** + * Serialized state cannot be loaded on a different platform + * from the one it was saved on for reasons other than endianness, + * such as word size dependence. + */ +#define RETRO_SERIALIZATION_QUIRK_PLATFORM_DEPENDENT (1 << 6) + +/** @} */ + +/** @defgroup SET_MEMORY_MAPS Memory Descriptors + * @{ + */ + +/** @defgroup RETRO_MEMDESC Memory Descriptor Flags + * Information about how the emulated hardware uses this portion of its address space. + * @{ + */ + +/** + * Indicates that this memory area won't be modified + * once \c retro_load_game has returned. + */ +#define RETRO_MEMDESC_CONST (1 << 0) + +/** + * Indicates a memory area with big-endian byte ordering, + * as opposed to the default of little-endian. + */ +#define RETRO_MEMDESC_BIGENDIAN (1 << 1) + +/** + * Indicates a memory area that is used for the emulated system's main RAM. + */ +#define RETRO_MEMDESC_SYSTEM_RAM (1 << 2) + +/** + * Indicates a memory area that is used for the emulated system's save RAM, + * usually found on a game cartridge as battery-backed RAM or flash memory. + */ +#define RETRO_MEMDESC_SAVE_RAM (1 << 3) + +/** + * Indicates a memory area that is used for the emulated system's video RAM, + * usually found on a console's GPU (or local equivalent). + */ +#define RETRO_MEMDESC_VIDEO_RAM (1 << 4) + +/** + * Indicates a memory area that requires all accesses + * to be aligned to 2 bytes or their own size + * (whichever is smaller). + */ +#define RETRO_MEMDESC_ALIGN_2 (1 << 16) + +/** + * Indicates a memory area that requires all accesses + * to be aligned to 4 bytes or their own size + * (whichever is smaller). + */ +#define RETRO_MEMDESC_ALIGN_4 (2 << 16) + +/** + * Indicates a memory area that requires all accesses + * to be aligned to 8 bytes or their own size + * (whichever is smaller). + */ +#define RETRO_MEMDESC_ALIGN_8 (3 << 16) + +/** + * Indicates a memory area that requires all accesses + * to be at least 2 bytes long. + */ +#define RETRO_MEMDESC_MINSIZE_2 (1 << 24) + +/** + * Indicates a memory area that requires all accesses + * to be at least 4 bytes long. + */ +#define RETRO_MEMDESC_MINSIZE_4 (2 << 24) + +/** + * Indicates a memory area that requires all accesses + * to be at least 8 bytes long. + */ +#define RETRO_MEMDESC_MINSIZE_8 (3 << 24) + +/** @} */ + +/** + * A mapping from a region of the emulated console's address space + * to the host's address space. + * + * Can be used to map an address in the console's address space + * to the host's address space, like so: + * + * @code + * void* emu_to_host(void* addr, struct retro_memory_descriptor* descriptor) + * { + * return descriptor->ptr + (addr & ~descriptor->disconnect) - descriptor->start; + * } + * @endcode + * + * @see RETRO_ENVIRONMENT_SET_MEMORY_MAPS + */ +struct retro_memory_descriptor +{ + /** + * A bitwise \c OR of one or more \ref RETRO_MEMDESC "flags" + * that describe how the emulated system uses this descriptor's address range. + * + * @note If \c ptr is \c NULL, + * then no flags should be set. + * @see RETRO_MEMDESC + */ + uint64_t flags; + + /** + * Pointer to the start of this memory region's buffer + * within the \em host's address space. + * The address listed here must be valid for the duration of the session; + * it must not be freed or modified by the frontend + * and it must not be moved by the core. + * + * May be \c NULL to indicate a lack of accessible memory + * at the emulated address given in \c start. + * + * @note Overlapping descriptors that include the same byte + * must have the same \c ptr value. + */ + void *ptr; + + /** + * The offset of this memory region, + * relative to the address given by \c ptr. + * + * @note It is recommended to use this field for address calculations + * instead of performing arithmetic on \c ptr. + */ + size_t offset; + + /** + * The starting address of this memory region + * within the emulated hardware's address space. + * + * @note Not represented as a pointer + * because it's unlikely to be valid on the host device. + */ + size_t start; + + /** + * A bitmask that specifies which bits of an address must match + * the bits of the \ref start address. + * + * Combines with \c disconnect to map an address to a memory block. + * + * If multiple memory descriptors can claim a particular byte, + * the first one defined in the \ref retro_memory_descriptor array applies. + * A bit which is set in \c start must also be set in this. + * + * Can be zero, in which case \c start and \c len represent + * the complete mapping for this region of memory + * (i.e. each byte is mapped exactly once). + * In this case, \c len must be a power of two. + */ + size_t select; + + /** + * A bitmask of bits that are \em not used for addressing. + * + * Any set bits are assumed to be disconnected from + * the emulated memory chip's address pins, + * and are therefore ignored when memory-mapping. + */ + size_t disconnect; + + /** + * The length of this memory region, in bytes. + * + * If applying \ref start and \ref disconnect to an address + * results in a value higher than this, + * the highest bit of the address is cleared. + * + * If the address is still too high, the next highest bit is cleared. + * Can be zero, in which case it's assumed to be + * bounded only by \ref select and \ref disconnect. + */ + size_t len; + + /** + * A short name for this address space. + * + * Names must meet the following requirements: + * + * \li Characters must be in the set [a-zA-Z0-9_-]. + * \li No more than 8 characters, plus a \c NULL terminator. + * \li Names are case-sensitive, but lowercase characters are discouraged. + * \li A name must not be the same as another name plus a character in the set \c [A-F0-9] + * (i.e. if an address space named "RAM" exists, + * then the names "RAM0", "RAM1", ..., "RAMF" are forbidden). + * This is to allow addresses to be named by each descriptor unambiguously, + * even if the areas overlap. + * \li May be \c NULL or empty (both are considered equivalent). + * + * Here are some examples of pairs of address space names: + * + * \li \em blank + \em blank: valid (multiple things may be mapped in the same namespace) + * \li \c Sp + \c Sp: valid (multiple things may be mapped in the same namespace) + * \li \c SRAM + \c VRAM: valid (neither is a prefix of the other) + * \li \c V + \em blank: valid (\c V is not in \c [A-F0-9]) + * \li \c a + \em blank: valid but discouraged (\c a is not in \c [A-F0-9]) + * \li \c a + \c A: valid but discouraged (neither is a prefix of the other) + * \li \c AR + \em blank: valid (\c R is not in \c [A-F0-9]) + * \li \c ARB + \em blank: valid (there's no \c AR namespace, + * so the \c B doesn't cause ambiguity). + * \li \em blank + \c B: invalid, because it's ambiguous which address space \c B1234 would refer to. + * + * The length of the address space's name can't be used to disambugiate, + * as extra information may be appended to it without a separator. + */ + const char *addrspace; + + /* TODO: When finalizing this one, add a description field, which should be + * "WRAM" or something roughly equally long. */ + + /* TODO: When finalizing this one, replace 'select' with 'limit', which tells + * which bits can vary and still refer to the same address (limit = ~select). + * TODO: limit? range? vary? something else? */ + + /* TODO: When finalizing this one, if 'len' is above what 'select' (or + * 'limit') allows, it's bankswitched. Bankswitched data must have both 'len' + * and 'select' != 0, and the mappings don't tell how the system switches the + * banks. */ + + /* TODO: When finalizing this one, fix the 'len' bit removal order. + * For len=0x1800, pointer 0x1C00 should go to 0x1400, not 0x0C00. + * Algorithm: Take bits highest to lowest, but if it goes above len, clear + * the most recent addition and continue on the next bit. + * TODO: Can the above be optimized? Is "remove the lowest bit set in both + * pointer and 'len'" equivalent? */ + + /* TODO: Some emulators (MAME?) emulate big endian systems by only accessing + * the emulated memory in 32-bit chunks, native endian. But that's nothing + * compared to Darek Mihocka + * (section Emulation 103 - Nearly Free Byte Reversal) - he flips the ENTIRE + * RAM backwards! I'll want to represent both of those, via some flags. + * + * I suspect MAME either didn't think of that idea, or don't want the #ifdef. + * Not sure which, nor do I really care. */ + + /* TODO: Some of those flags are unused and/or don't really make sense. Clean + * them up. */ +}; + +/** + * A list of regions within the emulated console's address space. + * + * The frontend may use the largest value of + * \ref retro_memory_descriptor::start + \ref retro_memory_descriptor::select + * in a certain namespace to infer the overall size of the address space. + * If the address space is larger than that, + * the last mapping in \ref descriptors should have \ref retro_memory_descriptor::ptr set to \c NULL + * and \ref retro_memory_descriptor::select should have all bits used in the address space set to 1. + * + * Here's an example set of descriptors for the SNES. + * + * @code{.c} + * struct retro_memory_map snes_descriptors = retro_memory_map + * { + * .descriptors = (struct retro_memory_descriptor[]) + * { + * // WRAM; must usually be mapped before the ROM, + * // as some SNES ROM mappers try to claim 0x7E0000 + * { .addrspace="WRAM", .start=0x7E0000, .len=0x20000 }, + * + * // SPC700 RAM + * { .addrspace="SPC700", .len=0x10000 }, + * + * // WRAM mirrors + * { .addrspace="WRAM", .start=0x000000, .select=0xC0E000, .len=0x2000 }, + * { .addrspace="WRAM", .start=0x800000, .select=0xC0E000, .len=0x2000 }, + * + * // WRAM mirror, alternate equivalent descriptor + * // (Various similar constructions can be created by combining parts of the above two.) + * { .addrspace="WRAM", .select=0x40E000, .disconnect=~0x1FFF }, + * + * // LoROM (512KB, mirrored a couple of times) + * { .addrspace="LoROM", .start=0x008000, .select=0x408000, .disconnect=0x8000, .len=512*1024, .flags=RETRO_MEMDESC_CONST }, + * { .addrspace="LoROM", .start=0x400000, .select=0x400000, .disconnect=0x8000, .len=512*1024, .flags=RETRO_MEMDESC_CONST }, + * + * // HiROM (4MB) + * { .addrspace="HiROM", .start=0x400000, .select=0x400000, .len=4*1024*1024, .flags=RETRO_MEMDESC_CONST }, + * { .addrspace="HiROM", .start=0x008000, .select=0x408000, .len=4*1024*1024, .offset=0x8000, .flags=RETRO_MEMDESC_CONST }, + * + * // ExHiROM (8MB) + * { .addrspace="ExHiROM", .start=0xC00000, .select=0xC00000, .len=4*1024*1024, .offset=0, .flags=RETRO_MEMDESC_CONST }, + * { .addrspace="ExHiROM", .start=0x400000, .select=0xC00000, .len=4*1024*1024, .offset=4*1024*1024, .flags=RETRO_MEMDESC_CONST }, + * { .addrspace="ExHiROM", .start=0x808000, .select=0xC08000, .len=4*1024*1024, .offset=0x8000, .flags=RETRO_MEMDESC_CONST }, + * { .addrspace="ExHiROM", .start=0x008000, .select=0xC08000, .len=4*1024*1024, .offset=4*1024*1024+0x8000, .flags=RETRO_MEMDESC_CONST }, + * + * // Clarifying the full size of the address space + * { .select=0xFFFFFF, .ptr=NULL }, + * }, + * .num_descriptors = 14, + * }; + * @endcode + * + * @see RETRO_ENVIRONMENT_SET_MEMORY_MAPS + */ +struct retro_memory_map +{ + /** + * Pointer to an array of memory descriptors, + * each of which describes part of the emulated console's address space. + */ + const struct retro_memory_descriptor *descriptors; + + /** The number of descriptors in \c descriptors. */ + unsigned num_descriptors; +}; + +/** @} */ + +/** @defgroup SET_CONTROLLER_INFO Controller Info + * @{ + */ + +/** + * Details about a controller (or controller configuration) + * supported by one of a core's emulated input ports. + * + * @see RETRO_ENVIRONMENT_SET_CONTROLLER_INFO + */ +struct retro_controller_description +{ + /** + * A human-readable label for the controller or configuration + * represented by this device type. + * Most likely the device's original brand name. + */ + const char *desc; + + /** + * A unique identifier that will be passed to \c retro_set_controller_port_device()'s \c device parameter. + * May be the ID of one of \ref RETRO_DEVICE "the generic controller types", + * or a subclass ID defined with \c RETRO_DEVICE_SUBCLASS. + * + * @see RETRO_DEVICE_SUBCLASS + */ + unsigned id; +}; + +/** + * Lists the types of controllers supported by + * one of core's emulated input ports. + * + * @see RETRO_ENVIRONMENT_SET_CONTROLLER_INFO + */ +struct retro_controller_info +{ + + /** + * A pointer to an array of device types supported by this controller port. + * + * @note Ports that support the same devices + * may share the same underlying array. + */ + const struct retro_controller_description *types; + + /** The number of elements in \c types. */ + unsigned num_types; +}; + +/** @} */ + +/** @defgroup SET_SUBSYSTEM_INFO Subsystems + * @{ + */ + +/** + * Information about a type of memory associated with a subsystem. + * Usually used for SRAM (save RAM). + * + * @see RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO + * @see retro_get_memory_data + * @see retro_get_memory_size + */ +struct retro_subsystem_memory_info +{ + /** + * The file extension the frontend should use + * to save this memory region to disk, e.g. "srm" or "sav". + */ + const char *extension; + + /** + * A constant that identifies this type of memory. + * Should be at least 0x100 (256) to avoid conflict + * with the standard libretro memory types, + * unless a subsystem uses the main platform's memory region. + * @see RETRO_MEMORY + */ + unsigned type; +}; + +/** + * Information about a type of ROM that a subsystem may use. + * Subsystems may use one or more ROMs at once, + * possibly of different types. + * + * @see RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO + * @see retro_subsystem_info + */ +struct retro_subsystem_rom_info +{ + /** + * Human-readable description of what the content represents, + * e.g. "Game Boy ROM". + */ + const char *desc; + + /** @copydoc retro_system_info::valid_extensions */ + const char *valid_extensions; + + /** @copydoc retro_system_info::need_fullpath */ + bool need_fullpath; + + /** @copydoc retro_system_info::block_extract */ + bool block_extract; + + /** + * Indicates whether this particular subsystem ROM is required. + * If \c true and the user doesn't provide a ROM, + * the frontend should not load the core. + * If \c false and the user doesn't provide a ROM, + * the frontend should pass a zeroed-out \c retro_game_info + * to the corresponding entry in \c retro_load_game_special(). + */ + bool required; + + /** + * Pointer to an array of memory descriptors that this subsystem ROM type uses. + * Useful for secondary cartridges that have their own save data. + * May be \c NULL, in which case this subsystem ROM's memory is not persisted by the frontend + * and \c num_memory should be zero. + */ + const struct retro_subsystem_memory_info *memory; + + /** The number of elements in the array pointed to by \c memory. */ + unsigned num_memory; +}; + +/** + * Information about a secondary platform that a core supports. + * @see RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO + */ +struct retro_subsystem_info +{ + /** + * A human-readable description of the subsystem type, + * usually the brand name of the original platform + * (e.g. "Super Game Boy"). + */ + const char *desc; + + /** + * A short machine-friendly identifier for the subsystem, + * usually an abbreviation of the platform name. + * For example, a Super Game Boy subsystem for a SNES core + * might use an identifier of "sgb". + * This identifier can be used for command-line interfaces, + * configuration, or other purposes. + * Must use lower-case alphabetical characters only (i.e. from a-z). + */ + const char *ident; + + /** + * The list of ROM types that this subsystem may use. + * + * The first entry is considered to be the "most significant" content, + * for the purposes of the frontend's categorization. + * E.g. with Super GameBoy, the first content should be the GameBoy ROM, + * as it is the most "significant" content to a user. + * + * If a frontend creates new files based on the content used (e.g. for savestates), + * it should derive the filenames from the name of the first ROM in this list. + * + * @note \c roms can have a single element, + * but this is usually a sign that the core should broaden its + * primary system info instead. + * + * @see \c retro_system_info + */ + const struct retro_subsystem_rom_info *roms; + + /** The length of the array given in \c roms. */ + unsigned num_roms; + + /** A unique identifier passed to retro_load_game_special(). */ + unsigned id; +}; + +/** @} */ + +/** @defgroup SET_PROC_ADDRESS_CALLBACK Core Function Pointers + * @{ */ + +/** + * The function pointer type that \c retro_get_proc_address_t returns. + * + * Despite the signature shown here, the original function may include any parameters and return type + * that respects the calling convention and C ABI. + * + * The frontend is expected to cast the function pointer to the correct type. + */ +typedef void (RETRO_CALLCONV *retro_proc_address_t)(void); + +/** + * Get a symbol from a libretro core. + * + * Cores should only return symbols that serve as libretro extensions. + * Frontends should not use this to obtain symbols to standard libretro entry points; + * instead, they should link to the core statically or use \c dlsym (or local equivalent). + * + * The symbol name must be equal to the function name. + * e.g. if void retro_foo(void); exists, the symbol in the compiled library must be called \c retro_foo. + * The returned function pointer must be cast to the corresponding type. + * + * @param \c sym The name of the symbol to look up. + * @return Pointer to the exposed function with the name given in \c sym, + * or \c NULL if one couldn't be found. + * @note The frontend is expected to know the returned pointer's type in advance + * so that it can be cast correctly. + * @note The core doesn't need to expose every possible function through this interface. + * It's enough to only expose the ones that it expects the frontend to use. + * @note The functions exposed through this interface + * don't need to be publicly exposed in the compiled library + * (e.g. via \c __declspec(dllexport)). + * @see RETRO_ENVIRONMENT_SET_PROC_ADDRESS_CALLBACK + */ +typedef retro_proc_address_t (RETRO_CALLCONV *retro_get_proc_address_t)(const char *sym); + +/** + * An interface that the frontend can use to get function pointers from the core. + * + * @note The returned function pointer will be invalidated once the core is unloaded. + * How and when that happens is up to the frontend. + * + * @see retro_get_proc_address_t + * @see RETRO_ENVIRONMENT_SET_PROC_ADDRESS_CALLBACK + */ +struct retro_get_proc_address_interface +{ + /** Set by the core. */ + retro_get_proc_address_t get_proc_address; +}; + +/** @} */ + +/** @defgroup GET_LOG_INTERFACE Logging + * @{ + */ + +/** + * The severity of a given message. + * The frontend may log messages differently depending on the level. + * It may also ignore log messages of a certain level. + * @see retro_log_callback + */ +enum retro_log_level +{ + /** The logged message is most likely not interesting to the user. */ + RETRO_LOG_DEBUG = 0, + + /** Information about the core operating normally. */ + RETRO_LOG_INFO, + + /** Indicates a potential problem, possibly one that the core can recover from. */ + RETRO_LOG_WARN, + + /** Indicates a degraded experience, if not failure. */ + RETRO_LOG_ERROR, + + /** Defined to ensure that sizeof(enum retro_log_level) == sizeof(int). Do not use. */ + RETRO_LOG_DUMMY = INT_MAX +}; + +/** + * Logs a message to the frontend. + * + * @param level The log level of the message. + * @param fmt The format string to log. + * Same format as \c printf. + * Behavior is undefined if this is \c NULL. + * @param ... Zero or more arguments used by the format string. + * Behavior is undefined if these don't match the ones expected by \c fmt. + * @see retro_log_level + * @see retro_log_callback + * @see RETRO_ENVIRONMENT_GET_LOG_INTERFACE + * @see printf + */ +typedef void (RETRO_CALLCONV *retro_log_printf_t)(enum retro_log_level level, + const char *fmt, ...); + +/** + * Details about how to make log messages. + * + * @see retro_log_printf_t + * @see RETRO_ENVIRONMENT_GET_LOG_INTERFACE + */ +struct retro_log_callback +{ + /** + * Called when logging a message. + * + * @note Set by the frontend. + */ + retro_log_printf_t log; +}; + +/** @} */ + +/** @defgroup GET_PERF_INTERFACE Performance Interface + * @{ + */ + +/** @defgroup RETRO_SIMD CPU Features + * @{ + */ + +/** + * Indicates CPU support for the SSE instruction set. + * + * @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSE + */ +#define RETRO_SIMD_SSE (1 << 0) + +/** + * Indicates CPU support for the SSE2 instruction set. + * + * @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSE2 + */ +#define RETRO_SIMD_SSE2 (1 << 1) + +/** Indicates CPU support for the AltiVec (aka VMX or Velocity Engine) instruction set. */ +#define RETRO_SIMD_VMX (1 << 2) + +/** Indicates CPU support for the VMX128 instruction set. Xbox 360 only. */ +#define RETRO_SIMD_VMX128 (1 << 3) + +/** + * Indicates CPU support for the AVX instruction set. + * + * @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#avxnewtechs=AVX + */ +#define RETRO_SIMD_AVX (1 << 4) + +/** + * Indicates CPU support for the NEON instruction set. + * @see https://developer.arm.com/architectures/instruction-sets/intrinsics/#f:@navigationhierarchiessimdisa=[Neon] + */ +#define RETRO_SIMD_NEON (1 << 5) + +/** + * Indicates CPU support for the SSE3 instruction set. + * + * @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSE3 + */ +#define RETRO_SIMD_SSE3 (1 << 6) + +/** + * Indicates CPU support for the SSSE3 instruction set. + * + * @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSSE3 + */ +#define RETRO_SIMD_SSSE3 (1 << 7) + +/** + * Indicates CPU support for the MMX instruction set. + * @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#techs=MMX + */ +#define RETRO_SIMD_MMX (1 << 8) + +/** Indicates CPU support for the MMXEXT instruction set. */ +#define RETRO_SIMD_MMXEXT (1 << 9) + +/** + * Indicates CPU support for the SSE4 instruction set. + * + * @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSE4_1 + */ +#define RETRO_SIMD_SSE4 (1 << 10) + +/** + * Indicates CPU support for the SSE4.2 instruction set. + * + * @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#ssetechs=SSE4_2 + */ +#define RETRO_SIMD_SSE42 (1 << 11) + +/** + * Indicates CPU support for the AVX2 instruction set. + * + * @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#avxnewtechs=AVX2 + */ +#define RETRO_SIMD_AVX2 (1 << 12) + +/** Indicates CPU support for the VFPU instruction set. PS2 and PSP only. + * + * @see https://pspdev.github.io/vfpu-docs + */ +#define RETRO_SIMD_VFPU (1 << 13) + +/** + * Indicates CPU support for Gekko SIMD extensions. GameCube only. + */ +#define RETRO_SIMD_PS (1 << 14) + +/** + * Indicates CPU support for AES instructions. + * + * @see https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#aestechs=AES&othertechs=AES + */ +#define RETRO_SIMD_AES (1 << 15) + +/** + * Indicates CPU support for the VFPv3 instruction set. + */ +#define RETRO_SIMD_VFPV3 (1 << 16) + +/** + * Indicates CPU support for the VFPv4 instruction set. + */ +#define RETRO_SIMD_VFPV4 (1 << 17) + +/** Indicates CPU support for the POPCNT instruction. */ +#define RETRO_SIMD_POPCNT (1 << 18) + +/** Indicates CPU support for the MOVBE instruction. */ +#define RETRO_SIMD_MOVBE (1 << 19) + +/** Indicates CPU support for the CMOV instruction. */ +#define RETRO_SIMD_CMOV (1 << 20) + +/** Indicates CPU support for the ASIMD instruction set. */ +#define RETRO_SIMD_ASIMD (1 << 21) + +/** @} */ + +/** + * An abstract unit of ticks. + * + * Usually nanoseconds or CPU cycles, + * but it depends on the platform and the frontend. + */ +typedef uint64_t retro_perf_tick_t; + +/** Time in microseconds. */ +typedef int64_t retro_time_t; + +/** + * A performance counter. + * + * Use this to measure the execution time of a region of code. + * @see retro_perf_callback + */ +struct retro_perf_counter +{ + /** + * A human-readable identifier for the counter. + * + * May be displayed by the frontend. + * Behavior is undefined if this is \c NULL. + */ + const char *ident; + + /** + * The time of the most recent call to \c retro_perf_callback::perf_start + * on this performance counter. + * + * @see retro_perf_start_t + */ + retro_perf_tick_t start; + + /** + * The total time spent within this performance counter's measured code, + * i.e. between calls to \c retro_perf_callback::perf_start and \c retro_perf_callback::perf_stop. + * + * Updated after each call to \c retro_perf_callback::perf_stop. + * @see retro_perf_stop_t + */ + retro_perf_tick_t total; + + /** + * The number of times this performance counter has been started. + * + * Updated after each call to \c retro_perf_callback::perf_start. + * @see retro_perf_start_t + */ + retro_perf_tick_t call_cnt; + + /** + * \c true if this performance counter has been registered by the frontend. + * Must be initialized to \c false by the core before registering it. + * @see retro_perf_register_t + */ + bool registered; +}; + +/** + * @returns The current system time in microseconds. + * @note Accuracy may vary by platform. + * The frontend should use the most accurate timer possible. + * @see RETRO_ENVIRONMENT_GET_PERF_INTERFACE + */ +typedef retro_time_t (RETRO_CALLCONV *retro_perf_get_time_usec_t)(void); + +/** + * @returns The number of ticks since some unspecified epoch. + * The exact meaning of a "tick" depends on the platform, + * but it usually refers to nanoseconds or CPU cycles. + * @see RETRO_ENVIRONMENT_GET_PERF_INTERFACE + */ +typedef retro_perf_tick_t (RETRO_CALLCONV *retro_perf_get_counter_t)(void); + +/** + * Returns a bitmask of detected CPU features. + * + * Use this for runtime dispatching of CPU-specific code. + * + * @returns A bitmask of detected CPU features. + * @see RETRO_ENVIRONMENT_GET_PERF_INTERFACE + * @see RETRO_SIMD + */ +typedef uint64_t (RETRO_CALLCONV *retro_get_cpu_features_t)(void); + +/** + * Asks the frontend to log or display the state of performance counters. + * How this is done depends on the frontend. + * Performance counters can be reviewed manually as well. + * + * @see RETRO_ENVIRONMENT_GET_PERF_INTERFACE + * @see retro_perf_counter + */ +typedef void (RETRO_CALLCONV *retro_perf_log_t)(void); + +/** + * Registers a new performance counter. + * + * If \c counter has already been registered beforehand, + * this function does nothing. + * + * @param counter The counter to register. + * \c counter::ident must be set to a unique identifier, + * and all other values in \c counter must be set to zero or \c false. + * Behavior is undefined if \c NULL. + * @post If \c counter is successfully registered, + * then \c counter::registered will be set to \c true. + * Otherwise, it will be set to \c false. + * Registration may fail if the frontend's maximum number of counters (if any) has been reached. + * @note The counter is owned by the core and must not be freed by the frontend. + * The frontend must also clean up any references to a core's performance counters + * before unloading it, otherwise undefined behavior may occur. + * @see retro_perf_start_t + * @see retro_perf_stop_t + */ +typedef void (RETRO_CALLCONV *retro_perf_register_t)(struct retro_perf_counter *counter); + +/** + * Starts a registered performance counter. + * + * Call this just before the code you want to measure. + * + * @param counter The counter to start. + * Behavior is undefined if \c NULL. + * @see retro_perf_stop_t + */ +typedef void (RETRO_CALLCONV *retro_perf_start_t)(struct retro_perf_counter *counter); + +/** + * Stops a registered performance counter. + * + * Call this just after the code you want to measure. + * + * @param counter The counter to stop. + * Behavior is undefined if \c NULL. + * @see retro_perf_start_t + * @see retro_perf_stop_t + */ +typedef void (RETRO_CALLCONV *retro_perf_stop_t)(struct retro_perf_counter *counter); + +/** + * An interface that the core can use to get performance information. + * + * Here's a usage example: + * + * @code{.c} + * #ifdef PROFILING + * // Wrapper macros to simplify using performance counters. + * // Optional; tailor these to your project's needs. + * #define RETRO_PERFORMANCE_INIT(perf_cb, name) static struct retro_perf_counter name = {#name}; if (!name.registered) perf_cb.perf_register(&(name)) + * #define RETRO_PERFORMANCE_START(perf_cb, name) perf_cb.perf_start(&(name)) + * #define RETRO_PERFORMANCE_STOP(perf_cb, name) perf_cb.perf_stop(&(name)) + * #else + * // Exclude the performance counters if profiling is disabled. + * #define RETRO_PERFORMANCE_INIT(perf_cb, name) ((void)0) + * #define RETRO_PERFORMANCE_START(perf_cb, name) ((void)0) + * #define RETRO_PERFORMANCE_STOP(perf_cb, name) ((void)0) + * #endif + * + * // Defined somewhere else in the core. + * extern struct retro_perf_callback perf_cb; + * + * void retro_run(void) + * { + * RETRO_PERFORMANCE_INIT(cb, interesting); + * RETRO_PERFORMANCE_START(cb, interesting); + * interesting_work(); + * RETRO_PERFORMANCE_STOP(cb, interesting); + * + * RETRO_PERFORMANCE_INIT(cb, maybe_slow); + * RETRO_PERFORMANCE_START(cb, maybe_slow); + * more_interesting_work(); + * RETRO_PERFORMANCE_STOP(cb, maybe_slow); + * } + * + * void retro_deinit(void) + * { + * // Asks the frontend to log the results of all performance counters. + * perf_cb.perf_log(); + * } + * @endcode + * + * All functions are set by the frontend. + * + * @see RETRO_ENVIRONMENT_GET_PERF_INTERFACE + */ +struct retro_perf_callback +{ + /** @copydoc retro_perf_get_time_usec_t */ + retro_perf_get_time_usec_t get_time_usec; + + /** @copydoc retro_perf_get_counter_t */ + retro_get_cpu_features_t get_cpu_features; + + /** @copydoc retro_perf_get_counter_t */ + retro_perf_get_counter_t get_perf_counter; + + /** @copydoc retro_perf_register_t */ + retro_perf_register_t perf_register; + + /** @copydoc retro_perf_start_t */ + retro_perf_start_t perf_start; + + /** @copydoc retro_perf_stop_t */ + retro_perf_stop_t perf_stop; + + /** @copydoc retro_perf_log_t */ + retro_perf_log_t perf_log; +}; + +/** @} */ + +/** + * @defgroup RETRO_SENSOR Sensor Interface + * @{ + */ + +/** + * Defines actions that can be performed on sensors. + * @note Cores should only enable sensors while they're actively being used; + * depending on the frontend and platform, + * enabling these sensors may impact battery life. + * + * @see RETRO_ENVIRONMENT_GET_SENSOR_INTERFACE + * @see retro_sensor_interface + * @see retro_set_sensor_state_t + */ +enum retro_sensor_action +{ + /** Enables accelerometer input, if one exists. */ + RETRO_SENSOR_ACCELEROMETER_ENABLE = 0, + + /** Disables accelerometer input, if one exists. */ + RETRO_SENSOR_ACCELEROMETER_DISABLE, + + /** Enables gyroscope input, if one exists. */ + RETRO_SENSOR_GYROSCOPE_ENABLE, + + /** Disables gyroscope input, if one exists. */ + RETRO_SENSOR_GYROSCOPE_DISABLE, + + /** Enables ambient light input, if a luminance sensor exists. */ + RETRO_SENSOR_ILLUMINANCE_ENABLE, + + /** Disables ambient light input, if a luminance sensor exists. */ + RETRO_SENSOR_ILLUMINANCE_DISABLE, + + /** @private Defined to ensure sizeof(enum retro_sensor_action) == sizeof(int). Do not use. */ + RETRO_SENSOR_DUMMY = INT_MAX +}; + +/** @defgroup RETRO_SENSOR_ID Sensor Value IDs + * @{ + */ +/* Id values for SENSOR types. */ + +/** + * Returns the device's acceleration along its local X axis minus the effect of gravity, in m/s^2. + * + * Positive values mean that the device is accelerating to the right. + * assuming the user is looking at it head-on. + */ +#define RETRO_SENSOR_ACCELEROMETER_X 0 + +/** + * Returns the device's acceleration along its local Y axis minus the effect of gravity, in m/s^2. + * + * Positive values mean that the device is accelerating upwards, + * assuming the user is looking at it head-on. + */ +#define RETRO_SENSOR_ACCELEROMETER_Y 1 + +/** + * Returns the the device's acceleration along its local Z axis minus the effect of gravity, in m/s^2. + * + * Positive values indicate forward acceleration towards the user, + * assuming the user is looking at the device head-on. + */ +#define RETRO_SENSOR_ACCELEROMETER_Z 2 + +/** + * Returns the angular velocity of the device around its local X axis, in radians per second. + * + * Positive values indicate counter-clockwise rotation. + * + * @note A radian is about 57 degrees, and a full 360-degree rotation is 2*pi radians. + * @see https://developer.android.com/reference/android/hardware/SensorEvent#sensor.type_gyroscope + * for guidance on using this value to derive a device's orientation. + */ +#define RETRO_SENSOR_GYROSCOPE_X 3 + +/** + * Returns the angular velocity of the device around its local Z axis, in radians per second. + * + * Positive values indicate counter-clockwise rotation. + * + * @note A radian is about 57 degrees, and a full 360-degree rotation is 2*pi radians. + * @see https://developer.android.com/reference/android/hardware/SensorEvent#sensor.type_gyroscope + * for guidance on using this value to derive a device's orientation. + */ +#define RETRO_SENSOR_GYROSCOPE_Y 4 + +/** + * Returns the angular velocity of the device around its local Z axis, in radians per second. + * + * Positive values indicate counter-clockwise rotation. + * + * @note A radian is about 57 degrees, and a full 360-degree rotation is 2*pi radians. + * @see https://developer.android.com/reference/android/hardware/SensorEvent#sensor.type_gyroscope + * for guidance on using this value to derive a device's orientation. + */ +#define RETRO_SENSOR_GYROSCOPE_Z 5 + +/** + * Returns the ambient illuminance (light intensity) of the device's environment, in lux. + * + * @see https://en.wikipedia.org/wiki/Lux for a table of common lux values. + */ +#define RETRO_SENSOR_ILLUMINANCE 6 +/** @} */ + +/** + * Adjusts the state of a sensor. + * + * @param port The device port of the controller that owns the sensor given in \c action. + * @param action The action to perform on the sensor. + * Different devices support different sensors. + * @param rate The rate at which the underlying sensor should be updated, in Hz. + * This should be treated as a hint, + * as some device sensors may not support the requested rate + * (if it's configurable at all). + * @returns \c true if the sensor state was successfully adjusted, \c false otherwise. + * @note If one of the \c RETRO_SENSOR_*_ENABLE actions fails, + * this likely means that the given sensor is not available + * on the provided \c port. + * @see retro_sensor_action + */ +typedef bool (RETRO_CALLCONV *retro_set_sensor_state_t)(unsigned port, + enum retro_sensor_action action, unsigned rate); + +/** + * Retrieves the current value reported by sensor. + * @param port The device port of the controller that owns the sensor given in \c id. + * @param id The sensor value to query. + * @returns The current sensor value. + * Exact semantics depend on the value given in \c id, + * but will return 0 for invalid arguments. + * + * @see RETRO_SENSOR_ID + */ +typedef float (RETRO_CALLCONV *retro_sensor_get_input_t)(unsigned port, unsigned id); + +/** + * An interface that cores can use to access device sensors. + * + * All function pointers are set by the frontend. + */ +struct retro_sensor_interface +{ + /** @copydoc retro_set_sensor_state_t */ + retro_set_sensor_state_t set_sensor_state; + + /** @copydoc retro_sensor_get_input_t */ + retro_sensor_get_input_t get_sensor_input; +}; + +/** @} */ + +/** @defgroup GET_CAMERA_INTERFACE Camera Interface + * @{ + */ + +/** + * Denotes the type of buffer in which the camera will store its input. + * + * Different camera drivers may support different buffer types. + * + * @see RETRO_ENVIRONMENT_GET_CAMERA_INTERFACE + * @see retro_camera_callback + */ +enum retro_camera_buffer +{ + /** + * Indicates that camera frames should be delivered to the core as an OpenGL texture. + * + * Requires that the core is using an OpenGL context via \c RETRO_ENVIRONMENT_SET_HW_RENDER. + * + * @see retro_camera_frame_opengl_texture_t + */ + RETRO_CAMERA_BUFFER_OPENGL_TEXTURE = 0, + + /** + * Indicates that camera frames should be delivered to the core as a raw buffer in memory. + * + * @see retro_camera_frame_raw_framebuffer_t + */ + RETRO_CAMERA_BUFFER_RAW_FRAMEBUFFER, + + /** + * @private Defined to ensure sizeof(enum retro_camera_buffer) == sizeof(int). + * Do not use. + */ + RETRO_CAMERA_BUFFER_DUMMY = INT_MAX +}; + +/** + * Starts an initialized camera. + * The camera is disabled by default, + * and must be enabled with this function before being used. + * + * Set by the frontend. + * + * @returns \c true if the camera was successfully started, \c false otherwise. + * Failure may occur if no actual camera is available, + * or if the frontend doesn't have permission to access it. + * @note Must be called in \c retro_run(). + * @see retro_camera_callback + */ +typedef bool (RETRO_CALLCONV *retro_camera_start_t)(void); + +/** + * Stops the running camera. + * + * Set by the frontend. + * + * @note Must be called in \c retro_run(). + * @warning The frontend may close the camera on its own when unloading the core, + * but this behavior is not guaranteed. + * Cores should clean up the camera before exiting. + * @see retro_camera_callback + */ +typedef void (RETRO_CALLCONV *retro_camera_stop_t)(void); + +/** + * Called by the frontend to report the state of the camera driver. + * + * @see retro_camera_callback + */ +typedef void (RETRO_CALLCONV *retro_camera_lifetime_status_t)(void); + +/** + * Called by the frontend to report a new camera frame, + * delivered as a raw buffer in memory. + * + * Set by the core. + * + * @param buffer Pointer to the camera's most recent video frame. + * Each pixel is in XRGB8888 format. + * The first pixel represents the top-left corner of the image + * (i.e. the Y axis goes downward). + * @param width The width of the frame given in \c buffer, in pixels. + * @param height The height of the frame given in \c buffer, in pixels. + * @param pitch The width of the frame given in \c buffer, in bytes. + * @warning \c buffer may be invalidated when this function returns, + * so the core should make its own copy of \c buffer if necessary. + * @see RETRO_CAMERA_BUFFER_RAW_FRAMEBUFFER + */ +typedef void (RETRO_CALLCONV *retro_camera_frame_raw_framebuffer_t)(const uint32_t *buffer, + unsigned width, unsigned height, size_t pitch); + +/** + * Called by the frontend to report a new camera frame, + * delivered as an OpenGL texture. + * + * @param texture_id The ID of the OpenGL texture that represents the camera's most recent frame. + * Owned by the frontend, and must not be modified by the core. + * @param texture_target The type of the texture given in \c texture_id. + * Usually either \c GL_TEXTURE_2D or \c GL_TEXTURE_RECTANGLE, + * but other types are allowed. + * @param affine A pointer to a 3x3 column-major affine matrix + * that can be used to transform pixel coordinates to texture coordinates. + * After transformation, the bottom-left corner should have coordinates of (0, 0) + * and the top-right corner should have coordinates of (1, 1) + * (or (width, height) for \c GL_TEXTURE_RECTANGLE). + * + * @note GL-specific typedefs (e.g. \c GLfloat and \c GLuint) are avoided here + * so that the API doesn't rely on gl.h. + * @warning \c texture_id and \c affine may be invalidated when this function returns, + * so the core should make its own copy of them if necessary. + */ +typedef void (RETRO_CALLCONV *retro_camera_frame_opengl_texture_t)(unsigned texture_id, + unsigned texture_target, const float *affine); + +/** + * An interface that the core can use to access a device's camera. + * + * @see RETRO_ENVIRONMENT_GET_CAMERA_INTERFACE + */ +struct retro_camera_callback +{ + /** + * Requested camera capabilities, + * given as a bitmask of \c retro_camera_buffer values. + * Set by the core. + * + * Here's a usage example: + * @code + * // Requesting support for camera data delivered as both an OpenGL texture and a pixel buffer: + * struct retro_camera_callback callback; + * callback.caps = (1 << RETRO_CAMERA_BUFFER_OPENGL_TEXTURE) | (1 << RETRO_CAMERA_BUFFER_RAW_FRAMEBUFFER); + * @endcode + */ + uint64_t caps; + + /** + * The desired width of the camera frame, in pixels. + * This is only a hint; the frontend may provide a different size. + * Set by the core. + * Use zero to let the frontend decide. + */ + unsigned width; + + /** + * The desired height of the camera frame, in pixels. + * This is only a hint; the frontend may provide a different size. + * Set by the core. + * Use zero to let the frontend decide. + */ + unsigned height; + + /** + * @copydoc retro_camera_start_t + * @see retro_camera_callback + */ + retro_camera_start_t start; + + /** + * @copydoc retro_camera_stop_t + * @see retro_camera_callback + */ + retro_camera_stop_t stop; + + /** + * @copydoc retro_camera_frame_raw_framebuffer_t + * @note If \c NULL, this function will not be called. + */ + retro_camera_frame_raw_framebuffer_t frame_raw_framebuffer; + + /** + * @copydoc retro_camera_frame_opengl_texture_t + * @note If \c NULL, this function will not be called. + */ + retro_camera_frame_opengl_texture_t frame_opengl_texture; + + /** + * Core-defined callback invoked by the frontend right after the camera driver is initialized + * (\em not when calling \c start). + * May be \c NULL, in which case this function is skipped. + */ + retro_camera_lifetime_status_t initialized; + + /** + * Core-defined callback invoked by the frontend + * right before the video camera driver is deinitialized + * (\em not when calling \c stop). + * May be \c NULL, in which case this function is skipped. + */ + retro_camera_lifetime_status_t deinitialized; +}; + +/** @} */ + +/** @defgroup GET_LOCATION_INTERFACE Location Interface + * @{ + */ + +/** @copydoc retro_location_callback::set_interval */ +typedef void (RETRO_CALLCONV *retro_location_set_interval_t)(unsigned interval_ms, + unsigned interval_distance); + +/** @copydoc retro_location_callback::start */ +typedef bool (RETRO_CALLCONV *retro_location_start_t)(void); + +/** @copydoc retro_location_callback::stop */ +typedef void (RETRO_CALLCONV *retro_location_stop_t)(void); + +/** @copydoc retro_location_callback::get_position */ +typedef bool (RETRO_CALLCONV *retro_location_get_position_t)(double *lat, double *lon, + double *horiz_accuracy, double *vert_accuracy); + +/** Function type that reports the status of the location service. */ +typedef void (RETRO_CALLCONV *retro_location_lifetime_status_t)(void); + +/** + * An interface that the core can use to access a device's location. + * + * @note It is the frontend's responsibility to request the necessary permissions + * from the operating system. + * @see RETRO_ENVIRONMENT_GET_LOCATION_INTERFACE + */ +struct retro_location_callback +{ + /** + * Starts listening the device's location service. + * + * The frontend will report changes to the device's location + * at the interval defined by \c set_interval. + * Set by the frontend. + * + * @return true if location services were successfully started, false otherwise. + * Note that this will return \c false if location services are disabled + * or the frontend doesn't have permission to use them. + * @note The device's location service may or may not have been enabled + * before the core calls this function. + */ + retro_location_start_t start; + + /** + * Stop listening to the device's location service. + * + * Set by the frontend. + * + * @note The location service itself may or may not + * be turned off by this function, + * depending on the platform and the frontend. + * @post The core will stop receiving location service updates. + */ + retro_location_stop_t stop; + + /** + * Returns the device's current coordinates. + * + * Set by the frontend. + * + * @param[out] lat Pointer to latitude, in degrees. + * Will be set to 0 if no change has occurred since the last call. + * Behavior is undefined if \c NULL. + * @param[out] lon Pointer to longitude, in degrees. + * Will be set to 0 if no change has occurred since the last call. + * Behavior is undefined if \c NULL. + * @param[out] horiz_accuracy Pointer to horizontal accuracy. + * Will be set to 0 if no change has occurred since the last call. + * Behavior is undefined if \c NULL. + * @param[out] vert_accuracy Pointer to vertical accuracy. + * Will be set to 0 if no change has occurred since the last call. + * Behavior is undefined if \c NULL. + */ + retro_location_get_position_t get_position; + + /** + * Sets the rate at which the location service should report updates. + * + * This is only a hint; the actual rate may differ. + * Sets the interval of time and/or distance at which to update/poll + * location-based data. + * + * Some platforms may only support one of the two parameters; + * cores should provide both to ensure compatibility. + * + * Set by the frontend. + * + * @param interval_ms The desired period of time between location updates, in milliseconds. + * @param interval_distance The desired distance between location updates, in meters. + */ + retro_location_set_interval_t set_interval; + + /** Called when the location service is initialized. Set by the core. Optional. */ + retro_location_lifetime_status_t initialized; + + /** Called when the location service is deinitialized. Set by the core. Optional. */ + retro_location_lifetime_status_t deinitialized; +}; + +/** @} */ + +/** @addtogroup GET_RUMBLE_INTERFACE + * @{ */ + +/** + * The type of rumble motor in a controller. + * + * Both motors can be controlled independently, + * and the strong motor does not override the weak motor. + * @see RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE + */ +enum retro_rumble_effect +{ + RETRO_RUMBLE_STRONG = 0, + RETRO_RUMBLE_WEAK = 1, + + /** @private Defined to ensure sizeof(enum retro_rumble_effect) == sizeof(int). Do not use. */ + RETRO_RUMBLE_DUMMY = INT_MAX +}; + +/** + * Requests a rumble state change for a controller. + * Set by the frontend. + * + * @param port The controller port to set the rumble state for. + * @param effect The rumble motor to set the strength of. + * @param strength The desired intensity of the rumble motor, ranging from \c 0 to \c 0xffff (inclusive). + * @return \c true if the requested rumble state was honored. + * If the controller doesn't support rumble, will return \c false. + * @note Calling this before the first \c retro_run() may return \c false. + * @see RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE + */ +typedef bool (RETRO_CALLCONV *retro_set_rumble_state_t)(unsigned port, + enum retro_rumble_effect effect, uint16_t strength); + +/** + * An interface that the core can use to set the rumble state of a controller. + * @see RETRO_ENVIRONMENT_GET_RUMBLE_INTERFACE + */ +struct retro_rumble_interface +{ + /** @copydoc retro_set_rumble_state_t */ + retro_set_rumble_state_t set_rumble_state; +}; + +/** @} */ + +/** + * Called by the frontend to request audio samples. + * The core should render audio within this function + * using the callback provided by \c retro_set_audio_sample or \c retro_set_audio_sample_batch. + * + * @warning This function may be called by any thread, + * therefore it must be thread-safe. + * @see RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK + * @see retro_audio_callback + * @see retro_audio_sample_batch_t + * @see retro_audio_sample_t + */ +typedef void (RETRO_CALLCONV *retro_audio_callback_t)(void); + +/** + * Called by the frontend to notify the core that it should pause or resume audio rendering. + * The initial state of the audio driver after registering this callback is \c false (inactive). + * + * @param enabled \c true if the frontend's audio driver is active. + * If so, the registered audio callback will be called regularly. + * If not, the audio callback will not be invoked until the next time + * the frontend calls this function with \c true. + * @warning This function may be called by any thread, + * therefore it must be thread-safe. + * @note Even if no audio samples are rendered, + * the core should continue to update its emulated platform's audio engine if necessary. + * @see RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK + * @see retro_audio_callback + * @see retro_audio_callback_t + */ +typedef void (RETRO_CALLCONV *retro_audio_set_state_callback_t)(bool enabled); + +/** + * An interface that the frontend uses to request audio samples from the core. + * @note To unregister a callback, pass a \c retro_audio_callback_t + * with both fields set to NULL. + * @see RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK + */ +struct retro_audio_callback +{ + /** @see retro_audio_callback_t */ + retro_audio_callback_t callback; + + /** @see retro_audio_set_state_callback_t */ + retro_audio_set_state_callback_t set_state; +}; + +typedef int64_t retro_usec_t; + +/** + * Called right before each iteration of \c retro_run + * if registered via RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK. + * + * @param usec Time since the last call to retro_run, in microseconds. + * If the frontend is manipulating the frame time + * (e.g. via fast-forward or slow motion), + * this value will be the reference value initially provided to the environment call. + * @see RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK + * @see retro_frame_time_callback + */ +typedef void (RETRO_CALLCONV *retro_frame_time_callback_t)(retro_usec_t usec); + +/** + * @see RETRO_ENVIRONMENT_SET_FRAME_TIME_CALLBACK + */ +struct retro_frame_time_callback +{ + /** + * Called to notify the core of the current frame time. + * If NULL, the frontend will clear its registered callback. + */ + retro_frame_time_callback_t callback; + + /** + * The ideal duration of one frame, in microseconds. + * Compute it as 1000000 / fps. + * The frontend will resolve rounding to ensure that framestepping, etc is exact. + */ + retro_usec_t reference; +}; + +/** @defgroup SET_AUDIO_BUFFER_STATUS_CALLBACK Audio Buffer Occupancy + * @{ + */ + +/** + * Notifies a libretro core of how full the frontend's audio buffer is. + * Set by the core, called by the frontend. + * It will be called right before \c retro_run() every frame. + * + * @param active \c true if the frontend's audio buffer is currently in use, + * \c false if audio is disabled in the frontend. + * @param occupancy A value between 0 and 100 (inclusive), + * corresponding to the frontend's audio buffer occupancy percentage. + * @param underrun_likely \c true if the frontend expects an audio buffer underrun + * during the next frame, which indicates that a core should attempt frame-skipping. + */ +typedef void (RETRO_CALLCONV *retro_audio_buffer_status_callback_t)( + bool active, unsigned occupancy, bool underrun_likely); + +/** + * A callback to register with the frontend to receive audio buffer occupancy information. + */ +struct retro_audio_buffer_status_callback +{ + /** @copydoc retro_audio_buffer_status_callback_t */ + retro_audio_buffer_status_callback_t callback; +}; + +/** @} */ + +/* Pass this to retro_video_refresh_t if rendering to hardware. + * Passing NULL to retro_video_refresh_t is still a frame dupe as normal. + * */ +#define RETRO_HW_FRAME_BUFFER_VALID ((void*)-1) + +/* Invalidates the current HW context. + * Any GL state is lost, and must not be deinitialized explicitly. + * If explicit deinitialization is desired by the libretro core, + * it should implement context_destroy callback. + * If called, all GPU resources must be reinitialized. + * Usually called when frontend reinits video driver. + * Also called first time video driver is initialized, + * allowing libretro core to initialize resources. + */ +typedef void (RETRO_CALLCONV *retro_hw_context_reset_t)(void); + +/* Gets current framebuffer which is to be rendered to. + * Could change every frame potentially. + */ +typedef uintptr_t (RETRO_CALLCONV *retro_hw_get_current_framebuffer_t)(void); + +/* Get a symbol from HW context. */ +typedef retro_proc_address_t (RETRO_CALLCONV *retro_hw_get_proc_address_t)(const char *sym); + +enum retro_hw_context_type +{ + RETRO_HW_CONTEXT_NONE = 0, + /* OpenGL 2.x. Driver can choose to use latest compatibility context. */ + RETRO_HW_CONTEXT_OPENGL = 1, + /* OpenGL ES 2.0. */ + RETRO_HW_CONTEXT_OPENGLES2 = 2, + /* Modern desktop core GL context. Use version_major/ + * version_minor fields to set GL version. */ + RETRO_HW_CONTEXT_OPENGL_CORE = 3, + /* OpenGL ES 3.0 */ + RETRO_HW_CONTEXT_OPENGLES3 = 4, + /* OpenGL ES 3.1+. Set version_major/version_minor. For GLES2 and GLES3, + * use the corresponding enums directly. */ + RETRO_HW_CONTEXT_OPENGLES_VERSION = 5, + + /* Vulkan, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE. */ + RETRO_HW_CONTEXT_VULKAN = 6, + + /* Direct3D11, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */ + RETRO_HW_CONTEXT_D3D11 = 7, + + /* Direct3D10, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */ + RETRO_HW_CONTEXT_D3D10 = 8, + + /* Direct3D12, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */ + RETRO_HW_CONTEXT_D3D12 = 9, + + /* Direct3D9, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */ + RETRO_HW_CONTEXT_D3D9 = 10, + + /** Dummy value to ensure sizeof(enum retro_hw_context_type) == sizeof(int). Do not use. */ + RETRO_HW_CONTEXT_DUMMY = INT_MAX +}; + +struct retro_hw_render_callback +{ + /* Which API to use. Set by libretro core. */ + enum retro_hw_context_type context_type; + + /* Called when a context has been created or when it has been reset. + * An OpenGL context is only valid after context_reset() has been called. + * + * When context_reset is called, OpenGL resources in the libretro + * implementation are guaranteed to be invalid. + * + * It is possible that context_reset is called multiple times during an + * application lifecycle. + * If context_reset is called without any notification (context_destroy), + * the OpenGL context was lost and resources should just be recreated + * without any attempt to "free" old resources. + */ + retro_hw_context_reset_t context_reset; + + /* Set by frontend. + * TODO: This is rather obsolete. The frontend should not + * be providing preallocated framebuffers. */ + retro_hw_get_current_framebuffer_t get_current_framebuffer; + + /* Set by frontend. + * Can return all relevant functions, including glClear on Windows. */ + retro_hw_get_proc_address_t get_proc_address; + + /* Set if render buffers should have depth component attached. + * TODO: Obsolete. */ + bool depth; + + /* Set if stencil buffers should be attached. + * TODO: Obsolete. */ + bool stencil; + + /* If depth and stencil are true, a packed 24/8 buffer will be added. + * Only attaching stencil is invalid and will be ignored. */ + + /* Use conventional bottom-left origin convention. If false, + * standard libretro top-left origin semantics are used. + * TODO: Move to GL specific interface. */ + bool bottom_left_origin; + + /* Major version number for core GL context or GLES 3.1+. */ + unsigned version_major; + + /* Minor version number for core GL context or GLES 3.1+. */ + unsigned version_minor; + + /* If this is true, the frontend will go very far to avoid + * resetting context in scenarios like toggling fullscreen, etc. + * TODO: Obsolete? Maybe frontend should just always assume this ... + */ + bool cache_context; + + /* The reset callback might still be called in extreme situations + * such as if the context is lost beyond recovery. + * + * For optimal stability, set this to false, and allow context to be + * reset at any time. + */ + + /* A callback to be called before the context is destroyed in a + * controlled way by the frontend. */ + retro_hw_context_reset_t context_destroy; + + /* OpenGL resources can be deinitialized cleanly at this step. + * context_destroy can be set to NULL, in which resources will + * just be destroyed without any notification. + * + * Even when context_destroy is non-NULL, it is possible that + * context_reset is called without any destroy notification. + * This happens if context is lost by external factors (such as + * notified by GL_ARB_robustness). + * + * In this case, the context is assumed to be already dead, + * and the libretro implementation must not try to free any OpenGL + * resources in the subsequent context_reset. + */ + + /* Creates a debug context. */ + bool debug_context; +}; + +/* Callback type passed in RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK. + * Called by the frontend in response to keyboard events. + * down is set if the key is being pressed, or false if it is being released. + * keycode is the RETROK value of the char. + * character is the text character of the pressed key. (UTF-32). + * key_modifiers is a set of RETROKMOD values or'ed together. + * + * The pressed/keycode state can be indepedent of the character. + * It is also possible that multiple characters are generated from a + * single keypress. + * Keycode events should be treated separately from character events. + * However, when possible, the frontend should try to synchronize these. + * If only a character is posted, keycode should be RETROK_UNKNOWN. + * + * Similarily if only a keycode event is generated with no corresponding + * character, character should be 0. + */ +typedef void (RETRO_CALLCONV *retro_keyboard_event_t)(bool down, unsigned keycode, + uint32_t character, uint16_t key_modifiers); + +struct retro_keyboard_callback +{ + retro_keyboard_event_t callback; +}; + +/** @defgroup SET_DISK_CONTROL_INTERFACE Disk Control + * + * Callbacks for inserting and removing disks from the emulated console at runtime. + * Should be provided by cores that support doing so. + * Cores should automate this process if possible, + * but some cases require the player's manual input. + * + * The steps for swapping disk images are generally as follows: + * + * \li Eject the emulated console's disk drive with \c set_eject_state(true). + * \li Insert the new disk image with \c set_image_index(index). + * \li Close the virtual disk tray with \c set_eject_state(false). + * + * @{ + */ + +/** + * Called by the frontend to open or close the emulated console's virtual disk tray. + * + * The frontend may only set the disk image index + * while the emulated tray is opened. + * + * If the emulated console's disk tray is already in the state given by \c ejected, + * then this function should return \c true without doing anything. + * The core should return \c false if it couldn't change the disk tray's state; + * this may happen if the console itself limits when the disk tray can be open or closed + * (e.g. to wait for the disc to stop spinning). + * + * @param ejected \c true if the virtual disk tray should be "ejected", + * \c false if it should be "closed". + * @return \c true if the virtual disk tray's state has been set to the given state, + * false if there was an error. + * @see retro_get_eject_state_t + */ +typedef bool (RETRO_CALLCONV *retro_set_eject_state_t)(bool ejected); + +/** + * Gets the current ejected state of the disk drive. + * The initial state is closed, i.e. \c false. + * + * @return \c true if the virtual disk tray is "ejected", + * i.e. it's open and a disk can be inserted. + * @see retro_set_eject_state_t + */ +typedef bool (RETRO_CALLCONV *retro_get_eject_state_t)(void); + +/** + * Gets the index of the current disk image, + * as determined by however the frontend orders disk images + * (such as m3u-formatted playlists or special directories). + * + * @return The index of the current disk image + * (starting with 0 for the first disk), + * or a value greater than or equal to \c get_num_images() if no disk is inserted. + * @see retro_get_num_images_t + */ +typedef unsigned (RETRO_CALLCONV *retro_get_image_index_t)(void); + +/** + * Inserts the disk image at the given index into the emulated console's drive. + * Can only be called while the disk tray is ejected + * (i.e. \c retro_get_eject_state_t returns \c true). + * + * If the emulated disk tray is ejected + * and already contains the disk image named by \c index, + * then this function should do nothing and return \c true. + * + * @param index The index of the disk image to insert, + * starting from 0 for the first disk. + * A value greater than or equal to \c get_num_images() + * represents the frontend removing the disk without inserting a new one. + * @return \c true if the disk image was successfully set. + * \c false if the disk tray isn't ejected or there was another error + * inserting a new disk image. + */ +typedef bool (RETRO_CALLCONV *retro_set_image_index_t)(unsigned index); + +/** + * @return The number of disk images which are available to use. + * These are most likely defined in a playlist file. + */ +typedef unsigned (RETRO_CALLCONV *retro_get_num_images_t)(void); + +struct retro_game_info; + +/** + * Replaces the disk image at the given index with a new disk. + * + * Replaces the disk image associated with index. + * Arguments to pass in info have same requirements as retro_load_game(). + * Virtual disk tray must be ejected when calling this. + * + * Passing \c NULL to this function indicates + * that the frontend has removed this disk image from its internal list. + * As a result, calls to this function can change the number of available disk indexes. + * + * For example, calling replace_image_index(1, NULL) + * will remove the disk image at index 1, + * and the disk image at index 2 (if any) + * will be moved to the newly-available index 1. + * + * @param index The index of the disk image to replace. + * @param info Details about the new disk image, + * or \c NULL if the disk image at the given index should be discarded. + * The semantics of each field are the same as in \c retro_load_game. + * @return \c true if the disk image was successfully replaced + * or removed from the playlist, + * \c false if the tray is not ejected + * or if there was an error. + */ +typedef bool (RETRO_CALLCONV *retro_replace_image_index_t)(unsigned index, + const struct retro_game_info *info); + +/** + * Adds a new index to the core's internal disk list. + * This will increment the return value from \c get_num_images() by 1. + * This image index cannot be used until a disk image has been set + * with \c replace_image_index. + * + * @return \c true if the core has added space for a new disk image + * and is ready to receive one. + */ +typedef bool (RETRO_CALLCONV *retro_add_image_index_t)(void); + +/** + * Sets the disk image that will be inserted into the emulated disk drive + * before \c retro_load_game is called. + * + * \c retro_load_game does not provide a way to ensure + * that a particular disk image in a playlist is inserted into the console; + * this function makes up for that. + * Frontends should call it immediately before \c retro_load_game, + * and the core should use the arguments + * to validate the disk image in \c retro_load_game. + * + * When content is loaded, the core should verify that the + * disk specified by \c index can be found at \c path. + * This is to guard against auto-selecting the wrong image + * if (for example) the user should modify an existing M3U playlist. + * We have to let the core handle this because + * \c set_initial_image() must be called before loading content, + * i.e. the frontend cannot access image paths in advance + * and thus cannot perform the error check itself. + * If \c index is invalid (i.e. index >= get_num_images()) + * or the disk image doesn't match the value given in \c path, + * the core should ignore the arguments + * and insert the disk at index 0 into the virtual disk tray. + * + * @warning If \c RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE is called within \c retro_load_game, + * then this function may not be executed. + * Set the disk control interface in \c retro_init if possible. + * + * @param index The index of the disk image within the playlist to set. + * @param path The path of the disk image to set as the first. + * The core should not load this path immediately; + * instead, it should use it within \c retro_load_game + * to verify that the correct disk image was loaded. + * @return \c true if the initial disk index was set, + * \c false if the arguments are invalid + * or the core doesn't support this function. + */ +typedef bool (RETRO_CALLCONV *retro_set_initial_image_t)(unsigned index, const char *path); + +/** + * Returns the path of the disk image at the given index + * on the host's file system. + * + * @param index The index of the disk image to get the path of. + * @param path A buffer to store the path in. + * @param len The size of \c path, in bytes. + * @return \c true if the disk image's location was successfully + * queried and copied into \c path, + * \c false if the index is invalid + * or the core couldn't locate the disk image. + */ +typedef bool (RETRO_CALLCONV *retro_get_image_path_t)(unsigned index, char *path, size_t len); + +/** + * Returns a friendly label for the given disk image. + * + * In the simplest case, this may be the disk image's file name + * with the extension omitted. + * For cores or games with more complex content requirements, + * the label can be used to provide information to help the player + * select a disk image to insert; + * for example, a core may label different kinds of disks + * (save data, level disk, installation disk, bonus content, etc.). + * with names that correspond to in-game prompts, + * so that the frontend can provide better guidance to the player. + * + * @param index The index of the disk image to return a label for. + * @param label A buffer to store the resulting label in. + * @param len The length of \c label, in bytes. + * @return \c true if the disk image at \c index is valid + * and a label was copied into \c label. + */ +typedef bool (RETRO_CALLCONV *retro_get_image_label_t)(unsigned index, char *label, size_t len); + +/** + * An interface that the frontend can use to exchange disks + * within the emulated console's disk drive. + * + * All function pointers are required. + * + * @deprecated This struct is superseded by \ref retro_disk_control_ext_callback. + * Only use this one to maintain compatibility + * with older cores and frontends. + * + * @see RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE + * @see retro_disk_control_ext_callback + */ +struct retro_disk_control_callback +{ + /** @copydoc retro_set_eject_state_t */ + retro_set_eject_state_t set_eject_state; + + /** @copydoc retro_get_eject_state_t */ + retro_get_eject_state_t get_eject_state; + + /** @copydoc retro_get_image_index_t */ + retro_get_image_index_t get_image_index; + + /** @copydoc retro_set_image_index_t */ + retro_set_image_index_t set_image_index; + + /** @copydoc retro_get_num_images_t */ + retro_get_num_images_t get_num_images; + + /** @copydoc retro_replace_image_index_t */ + retro_replace_image_index_t replace_image_index; + + /** @copydoc retro_add_image_index_t */ + retro_add_image_index_t add_image_index; +}; + +/** + * @copybrief retro_disk_control_callback + * + * All function pointers are required unless otherwise noted. + * + * @see RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE + */ +struct retro_disk_control_ext_callback +{ + /** @copydoc retro_set_eject_state_t */ + retro_set_eject_state_t set_eject_state; + + /** @copydoc retro_get_eject_state_t */ + retro_get_eject_state_t get_eject_state; + + /** @copydoc retro_get_image_index_t */ + retro_get_image_index_t get_image_index; + + /** @copydoc retro_set_image_index_t */ + retro_set_image_index_t set_image_index; + + /** @copydoc retro_get_num_images_t */ + retro_get_num_images_t get_num_images; + + /** @copydoc retro_replace_image_index_t */ + retro_replace_image_index_t replace_image_index; + + /** @copydoc retro_add_image_index_t */ + retro_add_image_index_t add_image_index; + + /** @copydoc retro_set_initial_image_t + * + * Optional; not called if \c NULL. + * + * @note The frontend will only try to record/restore the last-used disk index + * if both \c set_initial_image and \c get_image_path are implemented. + */ + retro_set_initial_image_t set_initial_image; + + /** + * @copydoc retro_get_image_path_t + * + * Optional; not called if \c NULL. + */ + retro_get_image_path_t get_image_path; + + /** + * @copydoc retro_get_image_label_t + * + * Optional; not called if \c NULL. + */ + retro_get_image_label_t get_image_label; +}; + +/** @} */ + +/* Definitions for RETRO_ENVIRONMENT_SET_NETPACKET_INTERFACE. + * A core can set it if sending and receiving custom network packets + * during a multiplayer session is desired. + */ + +/* Netpacket flags for retro_netpacket_send_t */ +#define RETRO_NETPACKET_UNRELIABLE 0 /* Packet to be sent unreliable, depending on network quality it might not arrive. */ +#define RETRO_NETPACKET_RELIABLE (1 << 0) /* Reliable packets are guaranteed to arrive at the target in the order they were sent. */ +#define RETRO_NETPACKET_UNSEQUENCED (1 << 1) /* Packet will not be sequenced with other packets and may arrive out of order. Cannot be set on reliable packets. */ +#define RETRO_NETPACKET_FLUSH_HINT (1 << 2) /* Request the packet and any previously buffered ones to be sent immediately */ + +/* Broadcast client_id for retro_netpacket_send_t */ +#define RETRO_NETPACKET_BROADCAST 0xFFFF + +/* Used by the core to send a packet to one or all connected players. + * A single packet sent via this interface can contain up to 64 KB of data. + * + * The client_id RETRO_NETPACKET_BROADCAST sends the packet as a broadcast to + * all connected players. This is supported from the host as well as clients. +* Otherwise, the argument indicates the player to send the packet to. + * + * A frontend must support sending reliable packets (RETRO_NETPACKET_RELIABLE). + * Unreliable packets might not be supported by the frontend, but the flags can + * still be specified. Reliable transmission will be used instead. + * + * Calling this with the flag RETRO_NETPACKET_FLUSH_HINT will send off the + * packet and any previously buffered ones immediately and without blocking. + * To only flush previously queued packets, buf or len can be passed as NULL/0. + * + * This function is not guaranteed to be thread-safe and must be called during + * retro_run or any of the netpacket callbacks passed with this interface. + */ +typedef void (RETRO_CALLCONV *retro_netpacket_send_t)(int flags, const void* buf, size_t len, uint16_t client_id); + +/* Optionally read any incoming packets without waiting for the end of the + * frame. While polling, retro_netpacket_receive_t and retro_netpacket_stop_t + * can be called. The core can perform this in a loop to do a blocking read, + * i.e., wait for incoming data, but needs to handle stop getting called and + * also give up after a short while to avoid freezing on a connection problem. + * It is a good idea to manually flush outgoing packets before calling this. + * + * This function is not guaranteed to be thread-safe and must be called during + * retro_run or any of the netpacket callbacks passed with this interface. + */ +typedef void (RETRO_CALLCONV *retro_netpacket_poll_receive_t)(void); + +/* Called by the frontend to signify that a multiplayer session has started. + * If client_id is 0 the local player is the host of the session and at this + * point no other player has connected yet. + * + * If client_id is > 0 the local player is a client connected to a host and + * at this point is already fully connected to the host. + * + * The core must store the function pointer send_fn and use it whenever it + * wants to send a packet. Optionally poll_receive_fn can be stored and used + * when regular receiving between frames is not enough. These function pointers + * remain valid until the frontend calls retro_netpacket_stop_t. + */ +typedef void (RETRO_CALLCONV *retro_netpacket_start_t)(uint16_t client_id, retro_netpacket_send_t send_fn, retro_netpacket_poll_receive_t poll_receive_fn); + +/* Called by the frontend when a new packet arrives which has been sent from + * another player with retro_netpacket_send_t. The client_id argument indicates + * who has sent the packet. + */ +typedef void (RETRO_CALLCONV *retro_netpacket_receive_t)(const void* buf, size_t len, uint16_t client_id); + +/* Called by the frontend when the multiplayer session has ended. + * Once this gets called the function pointers passed to + * retro_netpacket_start_t will not be valid anymore. + */ +typedef void (RETRO_CALLCONV *retro_netpacket_stop_t)(void); + +/* Called by the frontend every frame (between calls to retro_run while + * updating the state of the multiplayer session. + * This is a good place for the core to call retro_netpacket_send_t from. + */ +typedef void (RETRO_CALLCONV *retro_netpacket_poll_t)(void); + +/* Called by the frontend when a new player connects to the hosted session. + * This is only called on the host side, not for clients connected to the host. + * If this function returns false, the newly connected player gets dropped. + * This can be used for example to limit the number of players. + */ +typedef bool (RETRO_CALLCONV *retro_netpacket_connected_t)(uint16_t client_id); + +/* Called by the frontend when a player leaves or disconnects from the hosted session. + * This is only called on the host side, not for clients connected to the host. + */ +typedef void (RETRO_CALLCONV *retro_netpacket_disconnected_t)(uint16_t client_id); + +/** + * A callback interface for giving a core the ability to send and receive custom + * network packets during a multiplayer session between two or more instances + * of a libretro frontend. + * + * Normally during connection handshake the frontend will compare library_version + * used by both parties and show a warning if there is a difference. When the core + * supplies protocol_version, the frontend will check against this instead. + * + * @see RETRO_ENVIRONMENT_SET_NETPACKET_INTERFACE + */ +struct retro_netpacket_callback +{ + retro_netpacket_start_t start; + retro_netpacket_receive_t receive; + retro_netpacket_stop_t stop; /* Optional - may be NULL */ + retro_netpacket_poll_t poll; /* Optional - may be NULL */ + retro_netpacket_connected_t connected; /* Optional - may be NULL */ + retro_netpacket_disconnected_t disconnected; /* Optional - may be NULL */ + const char* protocol_version; /* Optional - if not NULL will be used instead of core version to decide if communication is compatible */ +}; + +/** + * The pixel format used for rendering. + * @see RETRO_ENVIRONMENT_SET_PIXEL_FORMAT + */ +enum retro_pixel_format +{ + /** + * 0RGB1555, native endian. + * Used as the default if \c RETRO_ENVIRONMENT_SET_PIXEL_FORMAT is not called. + * The most significant bit must be set to 0. + * @deprecated This format remains supported to maintain compatibility. + * New code should use RETRO_PIXEL_FORMAT_RGB565 instead. + * @see RETRO_PIXEL_FORMAT_RGB565 + */ + RETRO_PIXEL_FORMAT_0RGB1555 = 0, + + /** + * XRGB8888, native endian. + * The most significant byte (the X) is ignored. + */ + RETRO_PIXEL_FORMAT_XRGB8888 = 1, + + /** + * RGB565, native endian. + * This format is recommended if 16-bit pixels are desired, + * as it is available on a variety of devices and APIs. + */ + RETRO_PIXEL_FORMAT_RGB565 = 2, + + /** Defined to ensure that sizeof(retro_pixel_format) == sizeof(int). Do not use. */ + RETRO_PIXEL_FORMAT_UNKNOWN = INT_MAX +}; + +/** @defgroup GET_SAVESTATE_CONTEXT Savestate Context + * @{ + */ + +/** + * Details about how the frontend will use savestates. + * + * @see RETRO_ENVIRONMENT_GET_SAVESTATE_CONTEXT + * @see retro_serialize + */ +enum retro_savestate_context +{ + /** + * Standard savestate written to disk. + * May be loaded at any time, + * even in a separate session or on another device. + * + * Should not contain any pointers to code or data. + */ + RETRO_SAVESTATE_CONTEXT_NORMAL = 0, + + /** + * The savestate is guaranteed to be loaded + * within the same session, address space, and binary. + * Will not be written to disk or sent over the network; + * therefore, internal pointers to code or data are acceptable. + * May still be loaded or saved at any time. + * + * @note This context generally implies the use of runahead or rewinding, + * which may work by taking savestates multiple times per second. + * Savestate code that runs in this context should be fast. + */ + RETRO_SAVESTATE_CONTEXT_RUNAHEAD_SAME_INSTANCE = 1, + + /** + * The savestate is guaranteed to be loaded + * in the same session and by the same binary, + * but possibly by a different address space + * (e.g. for "second instance" runahead) + * + * Will not be written to disk or sent over the network, + * but may be loaded in a different address space. + * Therefore, the savestate must not contain pointers. + */ + RETRO_SAVESTATE_CONTEXT_RUNAHEAD_SAME_BINARY = 2, + + /** + * The savestate will not be written to disk, + * but no other guarantees are made. + * The savestate will almost certainly be loaded + * by a separate binary, device, and address space. + * + * This context is intended for use with frontends that support rollback netplay. + * Serialized state should omit any data that would unnecessarily increase bandwidth usage. + * Must not contain pointers, and integers must be saved in big-endian format. + * @see retro_endianness.h + * @see network_stream + */ + RETRO_SAVESTATE_CONTEXT_ROLLBACK_NETPLAY = 3, + + /** + * @private Defined to ensure sizeof(retro_savestate_context) == sizeof(int). + * Do not use. + */ + RETRO_SAVESTATE_CONTEXT_UNKNOWN = INT_MAX +}; + +/** @} */ + +/** @defgroup SET_MESSAGE User-Visible Messages + * + * @{ + */ + +/** + * Defines a message that the frontend will display to the user, + * as determined by RETRO_ENVIRONMENT_SET_MESSAGE. + * + * @deprecated This struct is superseded by \ref retro_message_ext, + * which provides more control over how a message is presented. + * Only use it for compatibility with older cores and frontends. + * + * @see RETRO_ENVIRONMENT_SET_MESSAGE + * @see retro_message_ext + */ +struct retro_message +{ + /** + * Null-terminated message to be displayed. + * If \c NULL or empty, the message will be ignored. + */ + const char *msg; + + /** Duration to display \c msg in frames. */ + unsigned frames; +}; + +/** + * The method that the frontend will use to display a message to the player. + * @see retro_message_ext + */ +enum retro_message_target +{ + /** + * Indicates that the frontent should display the given message + * using all other targets defined by \c retro_message_target at once. + */ + RETRO_MESSAGE_TARGET_ALL = 0, + + /** + * Indicates that the frontend should display the given message + * using the frontend's on-screen display, if available. + * + * @attention If the frontend allows players to customize or disable notifications, + * then they may not see messages sent to this target. + */ + RETRO_MESSAGE_TARGET_OSD, + + /** + * Indicates that the frontend should log the message + * via its usual logging mechanism, if available. + * + * This is not intended to be a substitute for \c RETRO_ENVIRONMENT_SET_LOG_INTERFACE. + * It is intended for the common use case of + * logging a player-facing message. + * + * This target should not be used for messages + * of type \c RETRO_MESSAGE_TYPE_STATUS or \c RETRO_MESSAGE_TYPE_PROGRESS, + * as it may add unnecessary noise to a log file. + * + * @see RETRO_ENVIRONMENT_SET_LOG_INTERFACE + */ + RETRO_MESSAGE_TARGET_LOG +}; + +/** + * A broad category for the type of message that the frontend will display. + * + * Each message type has its own use case, + * therefore the frontend should present each one differently. + * + * @note This is a hint that the frontend may ignore. + * The frontend should fall back to \c RETRO_MESSAGE_TYPE_NOTIFICATION + * for message types that it doesn't support. + */ +enum retro_message_type +{ + /** + * A standard on-screen message. + * + * Suitable for a variety of use cases, + * such as messages about errors + * or other important events. + * + * Frontends that display their own messages + * should display this type of core-generated message the same way. + */ + RETRO_MESSAGE_TYPE_NOTIFICATION = 0, + + /** + * An on-screen message that should be visually distinct + * from \c RETRO_MESSAGE_TYPE_NOTIFICATION messages. + * + * The exact meaning of "visually distinct" is left to the frontend, + * but this usually implies that the frontend shows the message + * in a way that it doesn't typically use for its own notices. + */ + RETRO_MESSAGE_TYPE_NOTIFICATION_ALT, + + /** + * Indicates a frequently-updated status display, + * rather than a standard notification. + * Status messages are intended to be displayed permanently while a core is running + * in a way that doesn't suggest user action is required. + * + * Here are some possible use cases for status messages: + * + * @li An internal framerate counter. + * @li Debugging information. + * Remember to let the player disable it in the core options. + * @li Core-specific state, such as when a microphone is active. + * + * The status message is displayed for the given duration, + * unless another status message of equal or greater priority is shown. + */ + RETRO_MESSAGE_TYPE_STATUS, + + /** + * Denotes a message that reports the progress + * of a long-running asynchronous task, + * such as when a core loads large files from disk or the network. + * + * The frontend should display messages of this type as a progress bar + * (or a progress spinner for indefinite tasks), + * where \c retro_message_ext::msg is the progress bar's title + * and \c retro_message_ext::progress sets the progress bar's length. + * + * This message type shouldn't be used for tasks that are expected to complete quickly. + */ + RETRO_MESSAGE_TYPE_PROGRESS +}; + +/** + * A core-provided message that the frontend will display to the player. + * + * @note The frontend is encouraged store these messages in a queue. + * However, it should not empty the queue of core-submitted messages upon exit; + * if a core exits with an error, it may want to use this API + * to show an error message to the player. + * + * The frontend should maintain its own copy of the submitted message + * and all subobjects, including strings. + * + * @see RETRO_ENVIRONMENT_SET_MESSAGE_EXT + */ +struct retro_message_ext +{ + /** + * The \c NULL-terminated text of a message to show to the player. + * Must not be \c NULL. + * + * @note The frontend must honor newlines in this string + * when rendering text to \c RETRO_MESSAGE_TARGET_OSD. + */ + const char *msg; + + /** + * The duration that \c msg will be displayed on-screen, in milliseconds. + * + * Ignored for \c RETRO_MESSAGE_TARGET_LOG. + */ + unsigned duration; + + /** + * The relative importance of this message + * when targeting \c RETRO_MESSAGE_TARGET_OSD. + * Higher values indicate higher priority. + * + * The frontend should use this to prioritize messages + * when it can't show all active messages at once, + * or to remove messages from its queue if it's full. + * + * The relative display order of messages with the same priority + * is left to the frontend's discretion, + * although we suggest breaking ties + * in favor of the most recently-submitted message. + * + * Frontends may handle deprioritized messages at their discretion; + * such messages may have their \c duration altered, + * be hidden without being delayed, + * or even be discarded entirely. + * + * @note In the reference frontend (RetroArch), + * the same priority values are used for frontend-generated notifications, + * which are typically between 0 and 3 depending upon importance. + * + * Ignored for \c RETRO_MESSAGE_TARGET_LOG. + */ + unsigned priority; + + /** + * The severity level of this message. + * + * The frontend may use this to filter or customize messages + * depending on the player's preferences. + * Here are some ideas: + * + * @li Use this to prioritize errors and warnings + * over higher-ranking info and debug messages. + * @li Render warnings or errors with extra visual feedback, + * e.g. with brighter colors or accompanying sound effects. + * + * @see RETRO_ENVIRONMENT_SET_LOG_INTERFACE + */ + enum retro_log_level level; + + /** + * The intended destination of this message. + * + * @see retro_message_target + */ + enum retro_message_target target; + + /** + * The intended semantics of this message. + * + * Ignored for \c RETRO_MESSAGE_TARGET_LOG. + * + * @see retro_message_type + */ + enum retro_message_type type; + + /** + * The progress of an asynchronous task. + * + * A value betwen 0 and 100 (inclusive) indicates the task's percentage, + * and a value of -1 indicates a task of unknown completion. + * + * @note Since message type is a hint, a frontend may ignore progress values. + * Where relevant, a core should include progress percentage within the message string, + * such that the message intent remains clear when displayed + * as a standard frontend-generated notification. + * + * Ignored for \c RETRO_MESSAGE_TARGET_LOG and for + * message types other than \c RETRO_MESSAGE_TYPE_PROGRESS. + */ + int8_t progress; +}; + +/** @} */ + +/* Describes how the libretro implementation maps a libretro input bind + * to its internal input system through a human readable string. + * This string can be used to better let a user configure input. */ +struct retro_input_descriptor +{ + /* Associates given parameters with a description. */ + unsigned port; + unsigned device; + unsigned index; + unsigned id; + + /* Human readable description for parameters. + * The pointer must remain valid until + * retro_unload_game() is called. */ + const char *description; +}; + +/** + * Contains basic information about the core. + * + * @see retro_get_system_info + * @warning All pointers are owned by the core + * and must remain valid throughout its lifetime. + */ +struct retro_system_info +{ + /** + * Descriptive name of the library. + * + * @note Should not contain any version numbers, etc. + */ + const char *library_name; + + /** + * Descriptive version of the core. + */ + const char *library_version; + + /** + * A pipe-delimited string list of file extensions that this core can load, e.g. "bin|rom|iso". + * Typically used by a frontend for filtering or core selection. + */ + const char *valid_extensions; + + /* Libretro cores that need to have direct access to their content + * files, including cores which use the path of the content files to + * determine the paths of other files, should set need_fullpath to true. + * + * Cores should strive for setting need_fullpath to false, + * as it allows the frontend to perform patching, etc. + * + * If need_fullpath is true and retro_load_game() is called: + * - retro_game_info::path is guaranteed to have a valid path + * - retro_game_info::data and retro_game_info::size are invalid + * + * If need_fullpath is false and retro_load_game() is called: + * - retro_game_info::path may be NULL + * - retro_game_info::data and retro_game_info::size are guaranteed + * to be valid + * + * See also: + * - RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY + * - RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY + */ + bool need_fullpath; + + /* If true, the frontend is not allowed to extract any archives before + * loading the real content. + * Necessary for certain libretro implementations that load games + * from zipped archives. */ + bool block_extract; +}; + +/* Defines overrides which modify frontend handling of + * specific content file types. + * An array of retro_system_content_info_override is + * passed to RETRO_ENVIRONMENT_SET_CONTENT_INFO_OVERRIDE + * NOTE: In the following descriptions, references to + * retro_load_game() may be replaced with + * retro_load_game_special() */ +struct retro_system_content_info_override +{ + /* A list of file extensions for which the override + * should apply, delimited by a 'pipe' character + * (e.g. "md|sms|gg") + * Permitted file extensions are limited to those + * included in retro_system_info::valid_extensions + * and/or retro_subsystem_rom_info::valid_extensions */ + const char *extensions; + + /* Overrides the need_fullpath value set in + * retro_system_info and/or retro_subsystem_rom_info. + * To reiterate: + * + * If need_fullpath is true and retro_load_game() is called: + * - retro_game_info::path is guaranteed to contain a valid + * path to an existent file + * - retro_game_info::data and retro_game_info::size are invalid + * + * If need_fullpath is false and retro_load_game() is called: + * - retro_game_info::path may be NULL + * - retro_game_info::data and retro_game_info::size are guaranteed + * to be valid + * + * In addition: + * + * If need_fullpath is true and retro_load_game() is called: + * - retro_game_info_ext::full_path is guaranteed to contain a valid + * path to an existent file + * - retro_game_info_ext::archive_path may be NULL + * - retro_game_info_ext::archive_file may be NULL + * - retro_game_info_ext::dir is guaranteed to contain a valid path + * to the directory in which the content file exists + * - retro_game_info_ext::name is guaranteed to contain the + * basename of the content file, without extension + * - retro_game_info_ext::ext is guaranteed to contain the + * extension of the content file in lower case format + * - retro_game_info_ext::data and retro_game_info_ext::size + * are invalid + * + * If need_fullpath is false and retro_load_game() is called: + * - If retro_game_info_ext::file_in_archive is false: + * - retro_game_info_ext::full_path is guaranteed to contain + * a valid path to an existent file + * - retro_game_info_ext::archive_path may be NULL + * - retro_game_info_ext::archive_file may be NULL + * - retro_game_info_ext::dir is guaranteed to contain a + * valid path to the directory in which the content file exists + * - retro_game_info_ext::name is guaranteed to contain the + * basename of the content file, without extension + * - retro_game_info_ext::ext is guaranteed to contain the + * extension of the content file in lower case format + * - If retro_game_info_ext::file_in_archive is true: + * - retro_game_info_ext::full_path may be NULL + * - retro_game_info_ext::archive_path is guaranteed to + * contain a valid path to an existent compressed file + * inside which the content file is located + * - retro_game_info_ext::archive_file is guaranteed to + * contain a valid path to an existent content file + * inside the compressed file referred to by + * retro_game_info_ext::archive_path + * e.g. for a compressed file '/path/to/foo.zip' + * containing 'bar.sfc' + * > retro_game_info_ext::archive_path will be '/path/to/foo.zip' + * > retro_game_info_ext::archive_file will be 'bar.sfc' + * - retro_game_info_ext::dir is guaranteed to contain a + * valid path to the directory in which the compressed file + * (containing the content file) exists + * - retro_game_info_ext::name is guaranteed to contain + * EITHER + * 1) the basename of the compressed file (containing + * the content file), without extension + * OR + * 2) the basename of the content file inside the + * compressed file, without extension + * In either case, a core should consider 'name' to + * be the canonical name/ID of the the content file + * - retro_game_info_ext::ext is guaranteed to contain the + * extension of the content file inside the compressed file, + * in lower case format + * - retro_game_info_ext::data and retro_game_info_ext::size are + * guaranteed to be valid */ + bool need_fullpath; + + /* If need_fullpath is false, specifies whether the content + * data buffer available in retro_load_game() is 'persistent' + * + * If persistent_data is false and retro_load_game() is called: + * - retro_game_info::data and retro_game_info::size + * are valid only until retro_load_game() returns + * - retro_game_info_ext::data and retro_game_info_ext::size + * are valid only until retro_load_game() returns + * + * If persistent_data is true and retro_load_game() is called: + * - retro_game_info::data and retro_game_info::size + * are valid until retro_deinit() returns + * - retro_game_info_ext::data and retro_game_info_ext::size + * are valid until retro_deinit() returns */ + bool persistent_data; +}; + +/* Similar to retro_game_info, but provides extended + * information about the source content file and + * game memory buffer status. + * And array of retro_game_info_ext is returned by + * RETRO_ENVIRONMENT_GET_GAME_INFO_EXT + * NOTE: In the following descriptions, references to + * retro_load_game() may be replaced with + * retro_load_game_special() */ +struct retro_game_info_ext +{ + /* - If file_in_archive is false, contains a valid + * path to an existent content file (UTF-8 encoded) + * - If file_in_archive is true, may be NULL */ + const char *full_path; + + /* - If file_in_archive is false, may be NULL + * - If file_in_archive is true, contains a valid path + * to an existent compressed file inside which the + * content file is located (UTF-8 encoded) */ + const char *archive_path; + + /* - If file_in_archive is false, may be NULL + * - If file_in_archive is true, contain a valid path + * to an existent content file inside the compressed + * file referred to by archive_path (UTF-8 encoded) + * e.g. for a compressed file '/path/to/foo.zip' + * containing 'bar.sfc' + * > archive_path will be '/path/to/foo.zip' + * > archive_file will be 'bar.sfc' */ + const char *archive_file; + + /* - If file_in_archive is false, contains a valid path + * to the directory in which the content file exists + * (UTF-8 encoded) + * - If file_in_archive is true, contains a valid path + * to the directory in which the compressed file + * (containing the content file) exists (UTF-8 encoded) */ + const char *dir; + + /* Contains the canonical name/ID of the content file + * (UTF-8 encoded). Intended for use when identifying + * 'complementary' content named after the loaded file - + * i.e. companion data of a different format (a CD image + * required by a ROM), texture packs, internally handled + * save files, etc. + * - If file_in_archive is false, contains the basename + * of the content file, without extension + * - If file_in_archive is true, then string is + * implementation specific. A frontend may choose to + * set a name value of: + * EITHER + * 1) the basename of the compressed file (containing + * the content file), without extension + * OR + * 2) the basename of the content file inside the + * compressed file, without extension + * RetroArch sets the 'name' value according to (1). + * A frontend that supports routine loading of + * content from archives containing multiple unrelated + * content files may set the 'name' value according + * to (2). */ + const char *name; + + /* - If file_in_archive is false, contains the extension + * of the content file in lower case format + * - If file_in_archive is true, contains the extension + * of the content file inside the compressed file, + * in lower case format */ + const char *ext; + + /* String of implementation specific meta-data. */ + const char *meta; + + /* Memory buffer of loaded game content. Will be NULL: + * IF + * - retro_system_info::need_fullpath is true and + * retro_system_content_info_override::need_fullpath + * is unset + * OR + * - retro_system_content_info_override::need_fullpath + * is true */ + const void *data; + + /* Size of game content memory buffer, in bytes */ + size_t size; + + /* True if loaded content file is inside a compressed + * archive */ + bool file_in_archive; + + /* - If data is NULL, value is unset/ignored + * - If data is non-NULL: + * - If persistent_data is false, data and size are + * valid only until retro_load_game() returns + * - If persistent_data is true, data and size are + * are valid until retro_deinit() returns */ + bool persistent_data; +}; + +/** + * Parameters describing the size and shape of the video frame. + * @see retro_system_av_info + * @see RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO + * @see RETRO_ENVIRONMENT_SET_GEOMETRY + * @see retro_get_system_av_info + */ +struct retro_game_geometry +{ + /** + * Nominal video width of game, in pixels. + * This will typically be the emulated platform's native video width + * (or its smallest, if the original hardware supports multiple resolutions). + */ + unsigned base_width; + + /** + * Nominal video height of game, in pixels. + * This will typically be the emulated platform's native video height + * (or its smallest, if the original hardware supports multiple resolutions). + */ + unsigned base_height; + + /** + * Maximum possible width of the game screen, in pixels. + * This will typically be the emulated platform's maximum video width. + * For cores that emulate platforms with multiple screens (such as the Nintendo DS), + * this should assume the core's widest possible screen layout (e.g. side-by-side). + * For cores that support upscaling the resolution, + * this should assume the highest supported scale factor is active. + */ + unsigned max_width; + + /** + * Maximum possible height of the game screen, in pixels. + * This will typically be the emulated platform's maximum video height. + * For cores that emulate platforms with multiple screens (such as the Nintendo DS), + * this should assume the core's tallest possible screen layout (e.g. vertical). + * For cores that support upscaling the resolution, + * this should assume the highest supported scale factor is active. + */ + unsigned max_height; /* Maximum possible height of game. */ + + /** + * Nominal aspect ratio of game. + * If zero or less, + * an aspect ratio of base_width / base_height is assumed. + * + * @note A frontend may ignore this setting. + */ + float aspect_ratio; +}; + +/** + * Parameters describing the timing of the video and audio. + * @see retro_system_av_info + * @see RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO + * @see retro_get_system_av_info + */ +struct retro_system_timing +{ + /** Video output refresh rate, in frames per second. */ + double fps; + + /** The audio output sample rate, in Hz. */ + double sample_rate; +}; + +/** + * Configures how the core's audio and video should be updated. + * @see RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO + * @see retro_get_system_av_info + */ +struct retro_system_av_info +{ + /** Parameters describing the size and shape of the video frame. */ + struct retro_game_geometry geometry; + + /** Parameters describing the timing of the video and audio. */ + struct retro_system_timing timing; +}; + +/** @defgroup SET_CORE_OPTIONS Core Options + * @{ + */ + +/** + * Represents \ref RETRO_ENVIRONMENT_GET_VARIABLE "a core option query". + * + * @note In \ref RETRO_ENVIRONMENT_SET_VARIABLES + * (which is a deprecated API), + * this \c struct serves as an option definition. + * + * @see RETRO_ENVIRONMENT_GET_VARIABLE + */ +struct retro_variable +{ + /** + * A unique key identifying this option. + * + * Should be a key for an option that was previously defined + * with \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 or similar. + * + * Should be prefixed with the core's name + * to minimize the risk of collisions with another core's options, + * as frontends are not required to use a namespacing scheme for storing options. + * For example, a core named "foo" might define an option named "foo_option". + * + * @note In \ref RETRO_ENVIRONMENT_SET_VARIABLES + * (which is a deprecated API), + * this field is used to define an option + * named by this key. + */ + const char *key; + + /** + * Value to be obtained. + * + * Set by the frontend to \c NULL if + * the option named by \ref key does not exist. + * + * @note In \ref RETRO_ENVIRONMENT_SET_VARIABLES + * (which is a deprecated API), + * this field is set by the core to define the possible values + * for an option named by \ref key. + * When used this way, it must be formatted as follows: + * @li The text before the first ';' is the option's human-readable title. + * @li A single space follows the ';'. + * @li The rest of the string is a '|'-delimited list of possible values, + * with the first one being the default. + */ + const char *value; +}; + +/** + * An argument that's used to show or hide a core option in the frontend. + * + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY + */ +struct retro_core_option_display +{ + /** + * The key for a core option that was defined with \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2, + * \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL, + * or their legacy equivalents. + */ + const char *key; + + /** + * Whether the option named by \c key + * should be displayed to the player in the frontend's core options menu. + * + * @note This value is a hint, \em not a requirement; + * the frontend is free to ignore this field. + */ + bool visible; +}; + +/** + * The maximum number of choices that can be defined for a given core option. + * + * This limit was chosen as a compromise between + * a core's flexibility and a streamlined user experience. + * + * @note A guiding principle of libretro's API design is that + * all common interactions (gameplay, menu navigation, etc.) + * should be possible without a keyboard. + * + * If you need more than 128 choices for a core option, + * consider simplifying your option structure. + * Here are some ideas: + * + * \li If a core option represents a numeric value, + * consider reducing the option's granularity + * (e.g. define time limits in increments of 5 seconds instead of 1 second). + * Providing a fixed set of values based on experimentation + * is also a good idea. + * \li If a core option represents a dynamically-built list of files, + * consider leaving out files that won't be useful. + * For example, if a core allows the player to choose a specific BIOS file, + * it can omit files of the wrong length or without a valid header. + * + * @see retro_core_option_definition + * @see retro_core_option_v2_definition + */ +#define RETRO_NUM_CORE_OPTION_VALUES_MAX 128 + +/** + * A descriptor for a particular choice within a core option. + * + * @note All option values are represented as strings. + * If you need to represent any other type, + * parse the string in \ref value. + * + * @see retro_core_option_v2_category + */ +struct retro_core_option_value +{ + /** + * The option value that the frontend will serialize. + * + * Must not be \c NULL or empty. + * No other hard limits are placed on this value's contents, + * but here are some suggestions: + * + * \li If the value represents a number, + * don't include any non-digit characters (units, separators, etc.). + * Instead, include that information in \c label. + * This will simplify parsing. + * \li If the value represents a file path, + * store it as a relative path with respect to one of the common libretro directories + * (e.g. \ref RETRO_ENVIRONMENT_GET_SYSTEM_DIRECTORY "the system directory" + * or \ref RETRO_ENVIRONMENT_GET_SAVE_DIRECTORY "the save directory"), + * and use forward slashes (\c "/") as directory separators. + * This will simplify cloud storage if supported by the frontend, + * as the same file may be used on multiple devices. + */ + const char *value; + + /** + * Human-readable name for \c value that the frontend should show to players. + * + * May be \c NULL, in which case the frontend + * should display \c value itself. + * + * Here are some guidelines for writing a good label: + * + * \li Make the option labels obvious + * so that they don't need to be explained in the description. + * \li Keep labels short, and don't use unnecessary words. + * For example, "OpenGL" is a better label than "OpenGL Mode". + * \li If the option represents a number, + * consider adding units, separators, or other punctuation + * into the label itself. + * For example, "5 seconds" is a better label than "5". + * \li If the option represents a number, use intuitive units + * that don't take a lot of digits to express. + * For example, prefer "1 minute" over "60 seconds" or "60,000 milliseconds". + */ + const char *label; +}; + +/** + * @copybrief retro_core_option_v2_definition + * + * @deprecated Use \ref retro_core_option_v2_definition instead, + * as it supports categorizing options into groups. + * Only use this \c struct to support older frontends or cores. + * + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL + */ +struct retro_core_option_definition +{ + /** @copydoc retro_core_option_v2_definition::key */ + const char *key; + + /** @copydoc retro_core_option_v2_definition::desc */ + const char *desc; + + /** @copydoc retro_core_option_v2_definition::info */ + const char *info; + + /** @copydoc retro_core_option_v2_definition::values */ + struct retro_core_option_value values[RETRO_NUM_CORE_OPTION_VALUES_MAX]; + + /** @copydoc retro_core_option_v2_definition::default_value */ + const char *default_value; +}; + +#ifdef __PS3__ +#undef local +#endif + +/** + * A variant of \ref retro_core_options that supports internationalization. + * + * @deprecated Use \ref retro_core_options_v2_intl instead, + * as it supports categorizing options into groups. + * Only use this \c struct to support older frontends or cores. + * + * @see retro_core_options + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL + * @see RETRO_ENVIRONMENT_GET_LANGUAGE + * @see retro_language + */ +struct retro_core_options_intl +{ + /** @copydoc retro_core_options_v2_intl::us */ + struct retro_core_option_definition *us; + + /** @copydoc retro_core_options_v2_intl::local */ + struct retro_core_option_definition *local; +}; + +/** + * A descriptor for a group of related core options. + * + * Here's an example category: + * + * @code + * { + * "cpu", + * "CPU Emulation", + * "Settings for CPU quirks." + * } + * @endcode + * + * @see retro_core_options_v2 + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL + */ +struct retro_core_option_v2_category +{ + /** + * A string that uniquely identifies this category within the core's options. + * Any \c retro_core_option_v2_definition whose \c category_key matches this + * is considered to be within this category. + * Different cores may use the same category keys, + * so namespacing them is not necessary. + * Valid characters are [a-zA-Z0-9_-]. + * + * Frontends should use this category to organize core options, + * but may customize this category's presentation in other ways. + * For example, a frontend may use common keys like "audio" or "gfx" + * to select an appropriate icon in its UI. + * + * Required; must not be \c NULL. + */ + const char *key; + + /** + * A brief human-readable name for this category, + * intended for the frontend to display to the player. + * This should be a name that's concise and descriptive, such as "Audio" or "Video". + * + * Required; must not be \c NULL. + */ + const char *desc; + + /** + * A human-readable description for this category, + * intended for the frontend to display to the player + * as secondary help text (e.g. a sublabel or a tooltip). + * Optional; may be \c NULL or an empty string. + */ + const char *info; +}; + +/** + * A descriptor for a particular core option and the values it may take. + * + * Supports categorizing options into groups, + * so as not to overwhelm the player. + * + * @see retro_core_option_v2_category + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL + */ +struct retro_core_option_v2_definition +{ + /** + * A unique identifier for this option that cores may use + * \ref RETRO_ENVIRONMENT_GET_VARIABLE "to query its value from the frontend". + * Must be unique within this core. + * + * Should be unique globally; + * the recommended method for doing so + * is to prefix each option with the core's name. + * For example, an option that controls the resolution for a core named "foo" + * should be named \c "foo_resolution". + * + * Valid key characters are in the set [a-zA-Z0-9_-]. + */ + const char *key; + + /** + * A human-readable name for this option, + * intended to be displayed by frontends that don't support + * categorizing core options. + * + * Required; must not be \c NULL or empty. + */ + const char *desc; + + /** + * A human-readable name for this option, + * intended to be displayed by frontends that support + * categorizing core options. + * + * This version may be slightly more concise than \ref desc, + * as it can rely on the structure of the options menu. + * For example, "Interface" is a good \c desc_categorized, + * as it can be displayed as a sublabel for a "Network" category. + * For \c desc, "Network Interface" would be more suitable. + * + * Optional; if this field or \c category_key is empty or \c NULL, + * \c desc will be used instead. + */ + const char *desc_categorized; + + /** + * A human-readable description of this option and its effects, + * intended to be displayed by frontends that don't support + * categorizing core options. + * + * @details Intended to be displayed as secondary help text, + * such as a tooltip or a sublabel. + * + * Here are some suggestions for writing a good description: + * + * \li Avoid technical jargon unless this option is meant for advanced users. + * If unavoidable, suggest one of the default options for those unsure. + * \li Don't repeat the option name in the description; + * instead, describe what the option name means. + * \li If an option requires a core restart or game reset to take effect, + * be sure to say so. + * \li Try to make the option labels obvious + * so that they don't need to be explained in the description. + * + * Optional; may be \c NULL. + */ + const char *info; + + /** + * @brief A human-readable description of this option and its effects, + * intended to be displayed by frontends that support + * categorizing core options. + * + * This version is provided to accommodate descriptions + * that reference other options by name, + * as options may have different user-facing names + * depending on whether the frontend supports categorization. + * + * @copydetails info + * + * If empty or \c NULL, \c info will be used instead. + * Will be ignored if \c category_key is empty or \c NULL. + */ + const char *info_categorized; + + /** + * The key of the category that this option belongs to. + * + * Optional; if equal to \ref retro_core_option_v2_category::key "a defined category", + * then this option shall be displayed by the frontend + * next to other options in this same category, + * assuming it supports doing so. + * Option categories are intended to be displayed in a submenu, + * but this isn't a hard requirement. + * + * If \c NULL, empty, or not equal to a defined category, + * then this option is considered uncategorized + * and the frontend shall display it outside of any category + * (most likely at a top-level menu). + * + * @see retro_core_option_v2_category + */ + const char *category_key; + + /** + * One or more possible values for this option, + * up to the limit of \ref RETRO_NUM_CORE_OPTION_VALUES_MAX. + * + * Terminated by a \c { NULL, NULL } element, + * although frontends should work even if all elements are used. + */ + struct retro_core_option_value values[RETRO_NUM_CORE_OPTION_VALUES_MAX]; + + /** + * The default value for this core option. + * Used if it hasn't been set, e.g. for new cores. + * Must equal one of the \ref value members in the \c values array, + * or else this option will be ignored. + */ + const char *default_value; +}; + +/** + * A set of core option descriptors and the categories that group them, + * suitable for enabling a core to be customized. + * + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 + */ +struct retro_core_options_v2 +{ + /** + * An array of \ref retro_core_option_v2_category "option categories", + * terminated by a zeroed-out category \c struct. + * + * Will be ignored if the frontend doesn't support core option categories. + * + * If \c NULL or ignored, all options will be treated as uncategorized. + * This most likely means that a frontend will display them at a top-level menu + * without any kind of hierarchy or grouping. + */ + struct retro_core_option_v2_category *categories; + + /** + * An array of \ref retro_core_option_v2_definition "core option descriptors", + * terminated by a zeroed-out definition \c struct. + * + * Required; must not be \c NULL. + */ + struct retro_core_option_v2_definition *definitions; +}; + +/** + * A variant of \ref retro_core_options_v2 that supports internationalization. + * + * @see retro_core_options_v2 + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL + * @see RETRO_ENVIRONMENT_GET_LANGUAGE + * @see retro_language + */ +struct retro_core_options_v2_intl +{ + /** + * Pointer to a core options set + * whose text is written in American English. + * + * This may be passed to \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 as-is + * if not using \c RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL. + * + * Required; must not be \c NULL. + */ + struct retro_core_options_v2 *us; + + /** + * Pointer to a core options set + * whose text is written in one of libretro's \ref retro_language "supported languages", + * most likely the one returned by \ref RETRO_ENVIRONMENT_GET_LANGUAGE. + * + * Structure is the same, but usage is slightly different: + * + * \li All text (except for keys and option values) + * should be written in whichever language + * is returned by \c RETRO_ENVIRONMENT_GET_LANGUAGE. + * \li All fields besides keys and option values may be \c NULL, + * in which case the corresponding string in \c us + * is used instead. + * \li All \ref retro_core_option_v2_definition::default_value "default option values" + * are taken from \c us. + * The defaults in this field are ignored. + * + * May be \c NULL, in which case \c us is used instead. + */ + struct retro_core_options_v2 *local; +}; + +/** + * Called by the frontend to determine if any core option's visibility has changed. + * + * Each time a frontend sets a core option, + * it should call this function to see if + * any core option should be made visible or invisible. + * + * May also be called after \ref retro_load_game "loading a game", + * to determine what the initial visibility of each option should be. + * + * Within this function, the core must update the visibility + * of any dynamically-hidden options + * using \ref RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY. + * + * @note All core options are visible by default, + * even during this function's first call. + * + * @return \c true if any core option's visibility was adjusted + * since the last call to this function. + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY + * @see retro_core_option_display + */ +typedef bool (RETRO_CALLCONV *retro_core_options_update_display_callback_t)(void); + +/** + * Callback registered by the core for the frontend to use + * when setting the visibility of each core option. + * + * @see RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY + * @see retro_core_option_display + */ +struct retro_core_options_update_display_callback +{ + /** + * @copydoc retro_core_options_update_display_callback_t + * + * Set by the core. + */ + retro_core_options_update_display_callback_t callback; +}; + +/** @} */ + +struct retro_game_info +{ + const char *path; /* Path to game, UTF-8 encoded. + * Sometimes used as a reference for building other paths. + * May be NULL if game was loaded from stdin or similar, + * but in this case some cores will be unable to load `data`. + * So, it is preferable to fabricate something here instead + * of passing NULL, which will help more cores to succeed. + * retro_system_info::need_fullpath requires + * that this path is valid. */ + const void *data; /* Memory buffer of loaded game. Will be NULL + * if need_fullpath was set. */ + size_t size; /* Size of memory buffer. */ + const char *meta; /* String of implementation specific meta-data. */ +}; + +/** @defgroup GET_CURRENT_SOFTWARE_FRAMEBUFFER Frontend-Owned Framebuffers + * @{ + */ + +/** @defgroup RETRO_MEMORY_ACCESS Framebuffer Memory Access Types + * @{ + */ + +/** Indicates that core will write to the framebuffer returned by the frontend. */ +#define RETRO_MEMORY_ACCESS_WRITE (1 << 0) + +/** Indicates that the core will read from the framebuffer returned by the frontend. */ +#define RETRO_MEMORY_ACCESS_READ (1 << 1) + +/** @} */ + +/** @defgroup RETRO_MEMORY_TYPE Framebuffer Memory Types + * @{ + */ + +/** + * Indicates that the returned framebuffer's memory is cached. + * If not set, random access to the buffer may be very slow. + */ +#define RETRO_MEMORY_TYPE_CACHED (1 << 0) + +/** @} */ + +/** + * A frame buffer owned by the frontend that a core may use for rendering. + * + * @see GET_CURRENT_SOFTWARE_FRAMEBUFFER + * @see retro_video_refresh_t + */ +struct retro_framebuffer +{ + /** + * Pointer to the beginning of the framebuffer provided by the frontend. + * The initial contents of this buffer are unspecified, + * as is the means used to map the memory; + * this may be defined in software, + * or it may be GPU memory mapped to RAM. + * + * If the framebuffer is used, + * this pointer must be passed to \c retro_video_refresh_t as-is. + * It is undefined behavior to pass an offset to this pointer. + * + * @warning This pointer is only guaranteed to be valid + * for the duration of the same \c retro_run iteration + * \ref GET_CURRENT_SOFTWARE_FRAMEBUFFER "that requested the framebuffer". + * Reuse of this pointer is undefined. + */ + void *data; + + /** + * The width of the framebuffer given in \c data, in pixels. + * Set by the core. + * + * @warning If the framebuffer is used, + * this value must be passed to \c retro_video_refresh_t as-is. + * It is undefined behavior to try to render \c data with any other width. + */ + unsigned width; + + /** + * The height of the framebuffer given in \c data, in pixels. + * Set by the core. + * + * @warning If the framebuffer is used, + * this value must be passed to \c retro_video_refresh_t as-is. + * It is undefined behavior to try to render \c data with any other height. + */ + unsigned height; + + /** + * The distance between the start of one scanline and the beginning of the next, in bytes. + * In practice this is usually equal to \c width times the pixel size, + * but that's not guaranteed. + * Sometimes called the "stride". + * + * @setby{frontend} + * @warning If the framebuffer is used, + * this value must be passed to \c retro_video_refresh_t as-is. + * It is undefined to try to render \c data with any other pitch. + */ + size_t pitch; + + /** + * The pixel format of the returned framebuffer. + * May be different than the format specified by the core in \c RETRO_ENVIRONMENT_SET_PIXEL_FORMAT, + * e.g. due to conversions. + * Set by the frontend. + * + * @see RETRO_ENVIRONMENT_SET_PIXEL_FORMAT + */ + enum retro_pixel_format format; + + /** + * One or more \ref RETRO_MEMORY_ACCESS "memory access flags" + * that specify how the core will access the memory in \c data. + * + * @setby{core} + */ + unsigned access_flags; + + /** + * Zero or more \ref RETRO_MEMORY_TYPE "memory type flags" + * that describe how the framebuffer's memory has been mapped. + * + * @setby{frontend} + */ + unsigned memory_flags; +}; + +/** @} */ + +/** @defgroup SET_FASTFORWARDING_OVERRIDE Fast-Forward Override + * @{ + */ + +/** + * Parameters that govern when and how the core takes control + * of fast-forwarding mode. + */ +struct retro_fastforwarding_override +{ + /** + * The factor by which the core will be sped up + * when \c fastforward is \c true. + * This value is used as follows: + * + * @li A value greater than 1.0 will run the core at + * the specified multiple of normal speed. + * For example, a value of 5.0 + * combined with a normal target rate of 60 FPS + * will result in a target rate of 300 FPS. + * The actual rate may be lower if the host's hardware can't keep up. + * @li A value of 1.0 will run the core at normal speed. + * @li A value between 0.0 (inclusive) and 1.0 (exclusive) + * will run the core as fast as the host system can manage. + * @li A negative value will let the frontend choose a factor. + * @li An infinite value or \c NaN results in undefined behavior. + * + * @attention Setting this value to less than 1.0 will \em not + * slow down the core. + */ + float ratio; + + /** + * If \c true, the frontend should activate fast-forwarding + * until this field is set to \c false or the core is unloaded. + */ + bool fastforward; + + /** + * If \c true, the frontend should display an on-screen notification or icon + * while \c fastforward is \c true (where supported). + * Otherwise, the frontend should not display any such notification. + */ + bool notification; + + /** + * If \c true, the core has exclusive control + * over enabling and disabling fast-forwarding + * via the \c fastforward field. + * The frontend will not be able to start or stop fast-forwarding + * until this field is set to \c false or the core is unloaded. + */ + bool inhibit_toggle; +}; + +/** @} */ + +/** + * During normal operation. + * + * @note Rate will be equal to the core's internal FPS. + */ +#define RETRO_THROTTLE_NONE 0 + +/** + * While paused or stepping single frames. + * + * @note Rate will be 0. + */ +#define RETRO_THROTTLE_FRAME_STEPPING 1 + +/** + * During fast forwarding. + * + * @note Rate will be 0 if not specifically limited to a maximum speed. + */ +#define RETRO_THROTTLE_FAST_FORWARD 2 + +/** + * During slow motion. + * + * @note Rate will be less than the core's internal FPS. + */ +#define RETRO_THROTTLE_SLOW_MOTION 3 + +/** + * While rewinding recorded save states. + * + * @note Rate can vary depending on the rewind speed or be 0 if the frontend + * is not aiming for a specific rate. + */ +#define RETRO_THROTTLE_REWINDING 4 + +/** + * While vsync is active in the video driver, and the target refresh rate is lower than the core's internal FPS. + * + * @note Rate is the target refresh rate. + */ +#define RETRO_THROTTLE_VSYNC 5 + +/** + * When the frontend does not throttle in any way. + * + * @note Rate will be 0. An example could be if no vsync or audio output is active. + */ +#define RETRO_THROTTLE_UNBLOCKED 6 + +/** + * Details about the actual rate an implementation is calling \c retro_run() at. + * + * @see RETRO_ENVIRONMENT_GET_THROTTLE_STATE + */ +struct retro_throttle_state +{ + /** + * The current throttling mode. + * + * @note Should be one of the \c RETRO_THROTTLE_* values. + * @see RETRO_THROTTLE_NONE + * @see RETRO_THROTTLE_FRAME_STEPPING + * @see RETRO_THROTTLE_FAST_FORWARD + * @see RETRO_THROTTLE_SLOW_MOTION + * @see RETRO_THROTTLE_REWINDING + * @see RETRO_THROTTLE_VSYNC + * @see RETRO_THROTTLE_UNBLOCKED + */ + unsigned mode; + + /** + * How many times per second the frontend aims to call retro_run. + * + * @note Depending on the mode, it can be 0 if there is no known fixed rate. + * This won't be accurate if the total processing time of the core and + * the frontend is longer than what is available for one frame. + */ + float rate; +}; + +/** @defgroup GET_MICROPHONE_INTERFACE Microphone Interface + * @{ + */ + +/** + * Opaque handle to a microphone that's been opened for use. + * The underlying object is accessed or created with \c retro_microphone_interface_t. + */ +typedef struct retro_microphone retro_microphone_t; + +/** + * Parameters for configuring a microphone. + * Some of these might not be honored, + * depending on the available hardware and driver configuration. + */ +typedef struct retro_microphone_params +{ + /** + * The desired sample rate of the microphone's input, in Hz. + * The microphone's input will be resampled, + * so cores can ask for whichever frequency they need. + * + * If zero, some reasonable default will be provided by the frontend + * (usually from its config file). + * + * @see retro_get_mic_rate_t + */ + unsigned rate; +} retro_microphone_params_t; + +/** + * @copydoc retro_microphone_interface::open_mic + */ +typedef retro_microphone_t *(RETRO_CALLCONV *retro_open_mic_t)(const retro_microphone_params_t *params); + +/** + * @copydoc retro_microphone_interface::close_mic + */ +typedef void (RETRO_CALLCONV *retro_close_mic_t)(retro_microphone_t *microphone); + +/** + * @copydoc retro_microphone_interface::get_params + */ +typedef bool (RETRO_CALLCONV *retro_get_mic_params_t)(const retro_microphone_t *microphone, retro_microphone_params_t *params); + +/** + * @copydoc retro_microphone_interface::set_mic_state + */ +typedef bool (RETRO_CALLCONV *retro_set_mic_state_t)(retro_microphone_t *microphone, bool state); + +/** + * @copydoc retro_microphone_interface::get_mic_state + */ +typedef bool (RETRO_CALLCONV *retro_get_mic_state_t)(const retro_microphone_t *microphone); + +/** + * @copydoc retro_microphone_interface::read_mic + */ +typedef int (RETRO_CALLCONV *retro_read_mic_t)(retro_microphone_t *microphone, int16_t* samples, size_t num_samples); + +/** + * The current version of the microphone interface. + * Will be incremented whenever \c retro_microphone_interface or \c retro_microphone_params_t + * receive new fields. + * + * Frontends using cores built against older mic interface versions + * should not access fields introduced in newer versions. + */ +#define RETRO_MICROPHONE_INTERFACE_VERSION 1 + +/** + * An interface for querying the microphone and accessing data read from it. + * + * @see RETRO_ENVIRONMENT_GET_MICROPHONE_INTERFACE + */ +struct retro_microphone_interface +{ + /** + * The version of this microphone interface. + * Set by the core to request a particular version, + * and set by the frontend to indicate the returned version. + * 0 indicates that the interface is invalid or uninitialized. + */ + unsigned interface_version; + + /** + * Initializes a new microphone. + * Assuming that microphone support is enabled and provided by the frontend, + * cores may call this function whenever necessary. + * A microphone could be opened throughout a core's lifetime, + * or it could wait until a microphone is plugged in to the emulated device. + * + * The returned handle will be valid until it's freed, + * even if the audio driver is reinitialized. + * + * This function is not guaranteed to be thread-safe. + * + * @param[in] args Parameters used to create the microphone. + * May be \c NULL, in which case the default value of each parameter will be used. + * + * @returns Pointer to the newly-opened microphone, + * or \c NULL if one couldn't be opened. + * This likely means that no microphone is plugged in and recognized, + * or the maximum number of supported microphones has been reached. + * + * @note Microphones are \em inactive by default; + * to begin capturing audio, call \c set_mic_state. + * @see retro_microphone_params_t + */ + retro_open_mic_t open_mic; + + /** + * Closes a microphone that was initialized with \c open_mic. + * Calling this function will stop all microphone activity + * and free up the resources that it allocated. + * Afterwards, the handle is invalid and must not be used. + * + * A frontend may close opened microphones when unloading content, + * but this behavior is not guaranteed. + * Cores should close their microphones when exiting, just to be safe. + * + * @param microphone Pointer to the microphone that was allocated by \c open_mic. + * If \c NULL, this function does nothing. + * + * @note The handle might be reused if another microphone is opened later. + */ + retro_close_mic_t close_mic; + + /** + * Returns the configured parameters of this microphone. + * These may differ from what was requested depending on + * the driver and device configuration. + * + * Cores should check these values before they start fetching samples. + * + * Will not change after the mic was opened. + * + * @param[in] microphone Opaque handle to the microphone + * whose parameters will be retrieved. + * @param[out] params The parameters object that the + * microphone's parameters will be copied to. + * + * @return \c true if the parameters were retrieved, + * \c false if there was an error. + */ + retro_get_mic_params_t get_params; + + /** + * Enables or disables the given microphone. + * Microphones are disabled by default + * and must be explicitly enabled before they can be used. + * Disabled microphones will not process incoming audio samples, + * and will therefore have minimal impact on overall performance. + * Cores may enable microphones throughout their lifetime, + * or only for periods where they're needed. + * + * Cores that accept microphone input should be able to operate without it; + * we suggest substituting silence in this case. + * + * @param microphone Opaque handle to the microphone + * whose state will be adjusted. + * This will have been provided by \c open_mic. + * @param state \c true if the microphone should receive audio input, + * \c false if it should be idle. + * @returns \c true if the microphone's state was successfully set, + * \c false if \c microphone is invalid + * or if there was an error. + */ + retro_set_mic_state_t set_mic_state; + + /** + * Queries the active state of a microphone at the given index. + * Will return whether the microphone is enabled, + * even if the driver is paused. + * + * @param microphone Opaque handle to the microphone + * whose state will be queried. + * @return \c true if the provided \c microphone is valid and active, + * \c false if not or if there was an error. + */ + retro_get_mic_state_t get_mic_state; + + /** + * Retrieves the input processed by the microphone since the last call. + * \em Must be called every frame unless \c microphone is disabled, + * similar to how \c retro_audio_sample_batch_t works. + * + * @param[in] microphone Opaque handle to the microphone + * whose recent input will be retrieved. + * @param[out] samples The buffer that will be used to store the microphone's data. + * Microphone input is in mono (i.e. one number per sample). + * Should be large enough to accommodate the expected number of samples per frame; + * for example, a 44.1kHz sample rate at 60 FPS would require space for 735 samples. + * @param[in] num_samples The size of the data buffer in samples (\em not bytes). + * Microphone input is in mono, so a "frame" and a "sample" are equivalent in length here. + * + * @return The number of samples that were copied into \c samples. + * If \c microphone is pending driver initialization, + * this function will copy silence of the requested length into \c samples. + * + * Will return -1 if the microphone is disabled, + * the audio driver is paused, + * or there was an error. + */ + retro_read_mic_t read_mic; +}; + +/** @} */ + +/** @defgroup GET_DEVICE_POWER Device Power + * @{ + */ + +/** + * Describes how a device is being powered. + * @see RETRO_ENVIRONMENT_GET_DEVICE_POWER + */ +enum retro_power_state +{ + /** + * Indicates that the frontend cannot report its power state at this time, + * most likely due to a lack of support. + * + * \c RETRO_ENVIRONMENT_GET_DEVICE_POWER will not return this value; + * instead, the environment callback will return \c false. + */ + RETRO_POWERSTATE_UNKNOWN = 0, + + /** + * Indicates that the device is running on its battery. + * Usually applies to portable devices such as handhelds, laptops, and smartphones. + */ + RETRO_POWERSTATE_DISCHARGING, + + /** + * Indicates that the device's battery is currently charging. + */ + RETRO_POWERSTATE_CHARGING, + + /** + * Indicates that the device is connected to a power source + * and that its battery has finished charging. + */ + RETRO_POWERSTATE_CHARGED, + + /** + * Indicates that the device is connected to a power source + * and that it does not have a battery. + * This usually suggests a desktop computer or a non-portable game console. + */ + RETRO_POWERSTATE_PLUGGED_IN +}; + +/** + * Indicates that an estimate is not available for the battery level or time remaining, + * even if the actual power state is known. + */ +#define RETRO_POWERSTATE_NO_ESTIMATE (-1) + +/** + * Describes the power state of the device running the frontend. + * @see RETRO_ENVIRONMENT_GET_DEVICE_POWER + */ +struct retro_device_power +{ + /** + * The current state of the frontend's power usage. + */ + enum retro_power_state state; + + /** + * A rough estimate of the amount of time remaining (in seconds) + * before the device powers off. + * This value depends on a variety of factors, + * so it is not guaranteed to be accurate. + * + * Will be set to \c RETRO_POWERSTATE_NO_ESTIMATE if \c state does not equal \c RETRO_POWERSTATE_DISCHARGING. + * May still be set to \c RETRO_POWERSTATE_NO_ESTIMATE if the frontend is unable to provide an estimate. + */ + int seconds; + + /** + * The approximate percentage of battery charge, + * ranging from 0 to 100 (inclusive). + * The device may power off before this reaches 0. + * + * The user might have configured their device + * to stop charging before the battery is full, + * so do not assume that this will be 100 in the \c RETRO_POWERSTATE_CHARGED state. + */ + int8_t percent; +}; + +/** @} */ + +/** + * @defgroup Callbacks + * @{ + */ + +/** + * Environment callback to give implementations a way of performing uncommon tasks. + * + * @note Extensible. + * + * @param cmd The command to run. + * @param data A pointer to the data associated with the command. + * + * @return Varies by callback, + * but will always return \c false if the command is not recognized. + * + * @see RETRO_ENVIRONMENT_SET_ROTATION + * @see retro_set_environment() + */ +typedef bool (RETRO_CALLCONV *retro_environment_t)(unsigned cmd, void *data); + +/** + * Render a frame. + * + * @note For performance reasons, it is highly recommended to have a frame + * that is packed in memory, i.e. pitch == width * byte_per_pixel. + * Certain graphic APIs, such as OpenGL ES, do not like textures + * that are not packed in memory. + * + * @param data A pointer to the frame buffer data with a pixel format of 15-bit \c 0RGB1555 native endian, unless changed with \c RETRO_ENVIRONMENT_SET_PIXEL_FORMAT. + * @param width The width of the frame buffer, in pixels. + * @param height The height frame buffer, in pixels. + * @param pitch The width of the frame buffer, in bytes. + * + * @see retro_set_video_refresh() + * @see RETRO_ENVIRONMENT_SET_PIXEL_FORMAT + * @see retro_pixel_format + */ +typedef void (RETRO_CALLCONV *retro_video_refresh_t)(const void *data, unsigned width, + unsigned height, size_t pitch); + +/** + * Renders a single audio frame. Should only be used if implementation generates a single sample at a time. + * + * @param left The left audio sample represented as a signed 16-bit native endian. + * @param right The right audio sample represented as a signed 16-bit native endian. + * + * @see retro_set_audio_sample() + * @see retro_set_audio_sample_batch() + */ +typedef void (RETRO_CALLCONV *retro_audio_sample_t)(int16_t left, int16_t right); + +/** + * Renders multiple audio frames in one go. + * + * @note Only one of the audio callbacks must ever be used. + * + * @param data A pointer to the audio sample data pairs to render. + * @param frames The number of frames that are represented in the data. One frame + * is defined as a sample of left and right channels, interleaved. + * For example: int16_t buf[4] = { l, r, l, r }; would be 2 frames. + * + * @return The number of samples that were processed. + * + * @see retro_set_audio_sample_batch() + * @see retro_set_audio_sample() + */ +typedef size_t (RETRO_CALLCONV *retro_audio_sample_batch_t)(const int16_t *data, + size_t frames); + +/** + * Polls input. + * + * @see retro_set_input_poll() + */ +typedef void (RETRO_CALLCONV *retro_input_poll_t)(void); + +/** + * Queries for input for player 'port'. + * + * @param port Which player 'port' to query. + * @param device Which device to query for. Will be masked with \c RETRO_DEVICE_MASK. + * @param index The input index to retrieve. + * The exact semantics depend on the device type given in \c device. + * @param id The ID of which value to query, like \c RETRO_DEVICE_ID_JOYPAD_B. + * @returns Depends on the provided arguments, + * but will return 0 if their values are unsupported + * by the frontend or the backing physical device. + * @note Specialization of devices such as \c RETRO_DEVICE_JOYPAD_MULTITAP that + * have been set with \c retro_set_controller_port_device() will still use the + * higher level \c RETRO_DEVICE_JOYPAD to request input. + * + * @see retro_set_input_state() + * @see RETRO_DEVICE_NONE + * @see RETRO_DEVICE_JOYPAD + * @see RETRO_DEVICE_MOUSE + * @see RETRO_DEVICE_KEYBOARD + * @see RETRO_DEVICE_LIGHTGUN + * @see RETRO_DEVICE_ANALOG + * @see RETRO_DEVICE_POINTER + */ +typedef int16_t (RETRO_CALLCONV *retro_input_state_t)(unsigned port, unsigned device, + unsigned index, unsigned id); + +/** + * Sets the environment callback. + * + * @param cb The function which is used when making environment calls. + * + * @note Guaranteed to be called before \c retro_init(). + * + * @see RETRO_ENVIRONMENT + */ +RETRO_API void retro_set_environment(retro_environment_t cb); + +/** + * Sets the video refresh callback. + * + * @param cb The function which is used when rendering a frame. + * + * @note Guaranteed to have been called before the first call to \c retro_run() is made. + */ +RETRO_API void retro_set_video_refresh(retro_video_refresh_t cb); + +/** + * Sets the audio sample callback. + * + * @param cb The function which is used when rendering a single audio frame. + * + * @note Guaranteed to have been called before the first call to \c retro_run() is made. + */ +RETRO_API void retro_set_audio_sample(retro_audio_sample_t cb); + +/** + * Sets the audio sample batch callback. + * + * @param cb The function which is used when rendering multiple audio frames in one go. + * + * @note Guaranteed to have been called before the first call to \c retro_run() is made. + */ +RETRO_API void retro_set_audio_sample_batch(retro_audio_sample_batch_t cb); + +/** + * Sets the input poll callback. + * + * @param cb The function which is used to poll the active input. + * + * @note Guaranteed to have been called before the first call to \c retro_run() is made. + */ +RETRO_API void retro_set_input_poll(retro_input_poll_t cb); + +/** + * Sets the input state callback. + * + * @param cb The function which is used to query the input state. + * + *@note Guaranteed to have been called before the first call to \c retro_run() is made. + */ +RETRO_API void retro_set_input_state(retro_input_state_t cb); + +/** + * @} + */ + +/** + * Called by the frontend when initializing a libretro core. + * + * @warning There are many possible "gotchas" with global state in dynamic libraries. + * Here are some to keep in mind: + *
    + *
  • Do not assume that the core was loaded by the operating system + * for the first time within this call. + * It may have been statically linked or retained from a previous session. + * Consequently, cores must not rely on global variables being initialized + * to their default values before this function is called; + * this also goes for object constructors in C++. + *
  • Although C++ requires that constructors be called for global variables, + * it does not require that their destructors be called + * if stored within a dynamic library's global scope. + *
  • If the core is statically linked to the frontend, + * global variables may be initialized when the frontend itself is initially executed. + *
+ * @see retro_deinit + */ +RETRO_API void retro_init(void); + +/** + * Called by the frontend when deinitializing a libretro core. + * The core must release all of its allocated resources before this function returns. + * + * @warning There are many possible "gotchas" with global state in dynamic libraries. + * Here are some to keep in mind: + *
    + *
  • Do not assume that the operating system will unload the core after this function returns, + * as the core may be linked statically or retained in memory. + * Cores should use this function to clean up all allocated resources + * and reset all global variables to their default states. + *
  • Do not assume that this core won't be loaded again after this function returns. + * It may be kept in memory by the frontend for later use, + * or it may be statically linked. + * Therefore, all global variables should be reset to their default states within this function. + *
  • C++ does not require that destructors be called + * for variables within a dynamic library's global scope. + * Therefore, global objects that own dynamically-managed resources + * (such as \c std::string or std::vector) + * should be kept behind pointers that are explicitly deallocated within this function. + *
+ * @see retro_init + */ +RETRO_API void retro_deinit(void); + +/** + * Retrieves which version of the libretro API is being used. + * + * @note This is used to validate ABI compatibility when the API is revised. + * + * @return Must return \c RETRO_API_VERSION. + * + * @see RETRO_API_VERSION + */ +RETRO_API unsigned retro_api_version(void); + +/** + * Gets statically known system info. + * + * @note Can be called at any time, even before retro_init(). + * + * @param info A pointer to a \c retro_system_info where the info is to be loaded into. This must be statically allocated. + */ +RETRO_API void retro_get_system_info(struct retro_system_info *info); + +/** + * Gets information about system audio/video timings and geometry. + * + * @note Can be called only after \c retro_load_game() has successfully completed. + * + * @note The implementation of this function might not initialize every variable + * if needed. For example, \c geom.aspect_ratio might not be initialized if + * the core doesn't desire a particular aspect ratio. + * + * @param info A pointer to a \c retro_system_av_info where the audio/video information should be loaded into. + * + * @see retro_system_av_info + */ +RETRO_API void retro_get_system_av_info(struct retro_system_av_info *info); + +/** + * Sets device to be used for player 'port'. + * + * By default, \c RETRO_DEVICE_JOYPAD is assumed to be plugged into all + * available ports. + * + * @note Setting a particular device type is not a guarantee that libretro cores + * will only poll input based on that particular device type. It is only a + * hint to the libretro core when a core cannot automatically detect the + * appropriate input device type on its own. It is also relevant when a + * core can change its behavior depending on device type. + * + * @note As part of the core's implementation of retro_set_controller_port_device, + * the core should call \c RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS to notify the + * frontend if the descriptions for any controls have changed as a + * result of changing the device type. + * + * @param port Which port to set the device for, usually indicates the player number. + * @param device Which device the given port is using. By default, \c RETRO_DEVICE_JOYPAD is assumed for all ports. + * + * @see RETRO_DEVICE_NONE + * @see RETRO_DEVICE_JOYPAD + * @see RETRO_DEVICE_MOUSE + * @see RETRO_DEVICE_KEYBOARD + * @see RETRO_DEVICE_LIGHTGUN + * @see RETRO_DEVICE_ANALOG + * @see RETRO_DEVICE_POINTER + * @see RETRO_ENVIRONMENT_SET_CONTROLLER_INFO + */ +RETRO_API void retro_set_controller_port_device(unsigned port, unsigned device); + +/** + * Resets the currently-loaded game. + * Cores should treat this as a soft reset (i.e. an emulated reset button) if possible, + * but hard resets are acceptable. + */ +RETRO_API void retro_reset(void); + +/** + * Runs the game for one video frame. + * + * During \c retro_run(), the \c retro_input_poll_t callback must be called at least once. + * + * @note If a frame is not rendered for reasons where a game "dropped" a frame, + * this still counts as a frame, and \c retro_run() should explicitly dupe + * a frame if \c RETRO_ENVIRONMENT_GET_CAN_DUPE returns true. In this case, + * the video callback can take a NULL argument for data. + * + * @see retro_input_poll_t + */ +RETRO_API void retro_run(void); + +/** + * Returns the amount of data the implementation requires to serialize internal state (save states). + * + * @note Between calls to \c retro_load_game() and \c retro_unload_game(), the + * returned size is never allowed to be larger than a previous returned + * value, to ensure that the frontend can allocate a save state buffer once. + * + * @return The amount of data the implementation requires to serialize the internal state. + * + * @see retro_serialize() + */ +RETRO_API size_t retro_serialize_size(void); + +/** + * Serializes the internal state. + * + * @param data A pointer to where the serialized data should be saved to. + * @param size The size of the memory. + * + * @return If failed, or size is lower than \c retro_serialize_size(), it + * should return false. On success, it will return true. + * + * @see retro_serialize_size() + * @see retro_unserialize() + */ +RETRO_API bool retro_serialize(void *data, size_t size); + +/** + * Unserialize the given state data, and load it into the internal state. + * + * @return Returns true if loading the state was successful, false otherwise. + * + * @see retro_serialize() + */ +RETRO_API bool retro_unserialize(const void *data, size_t size); + +/** + * Reset all the active cheats to their default disabled state. + * + * @see retro_cheat_set() + */ +RETRO_API void retro_cheat_reset(void); + +/** + * Enable or disable a cheat. + * + * @param index The index of the cheat to act upon. + * @param enabled Whether to enable or disable the cheat. + * @param code A string of the code used for the cheat. + * + * @see retro_cheat_reset() + */ +RETRO_API void retro_cheat_set(unsigned index, bool enabled, const char *code); + +/** + * Loads a game. + * + * @param game A pointer to a \c retro_game_info detailing information about the game to load. + * May be \c NULL if the core is loaded without content. + * + * @return Will return true when the game was loaded successfully, or false otherwise. + * + * @see retro_game_info + * @see RETRO_ENVIRONMENT_SET_SUPPORT_NO_GAME + */ +RETRO_API bool retro_load_game(const struct retro_game_info *game); + +/** + * Called when the frontend has loaded one or more "special" content files, + * typically through subsystems. + * + * @note Only necessary for cores that support subsystems. + * Others may return \c false or delegate to retro_load_game. + * + * @param game_type The type of game to load, + * as determined by \c retro_subsystem_info. + * @param info A pointer to an array of \c retro_game_info objects + * providing information about the loaded content. + * @param num_info The number of \c retro_game_info objects passed into the info parameter. + * @return \c true if loading is successful, false otherwise. + * If the core returns \c false, + * the frontend should abort the core + * and return to its main menu (if applicable). + * + * @see RETRO_ENVIRONMENT_GET_GAME_INFO_EXT + * @see RETRO_ENVIRONMENT_SET_SUBSYSTEM_INFO + * @see retro_load_game() + * @see retro_subsystem_info + */ +RETRO_API bool retro_load_game_special( + unsigned game_type, + const struct retro_game_info *info, size_t num_info +); + +/** + * Unloads the currently loaded game. + * + * @note This is called before \c retro_deinit(void). + * + * @see retro_load_game() + * @see retro_deinit() + */ +RETRO_API void retro_unload_game(void); + +/** + * Gets the region of the actively loaded content as either \c RETRO_REGION_NTSC or \c RETRO_REGION_PAL. + * @note This refers to the region of the content's intended television standard, + * not necessarily the region of the content's origin. + * For emulated consoles that don't use either standard + * (e.g. handhelds or post-HD platforms), + * the core should return \c RETRO_REGION_NTSC. + * @return The region of the actively loaded content. + * + * @see RETRO_REGION_NTSC + * @see RETRO_REGION_PAL + */ +RETRO_API unsigned retro_get_region(void); + +/** + * Get a region of memory. + * + * @param id The ID for the memory block that's desired to retrieve. Can be \c RETRO_MEMORY_SAVE_RAM, \c RETRO_MEMORY_RTC, \c RETRO_MEMORY_SYSTEM_RAM, or \c RETRO_MEMORY_VIDEO_RAM. + * + * @return A pointer to the desired region of memory, or NULL when not available. + * + * @see RETRO_MEMORY_SAVE_RAM + * @see RETRO_MEMORY_RTC + * @see RETRO_MEMORY_SYSTEM_RAM + * @see RETRO_MEMORY_VIDEO_RAM + */ +RETRO_API void *retro_get_memory_data(unsigned id); + +/** + * Gets the size of the given region of memory. + * + * @param id The ID for the memory block to check the size of. Can be RETRO_MEMORY_SAVE_RAM, RETRO_MEMORY_RTC, RETRO_MEMORY_SYSTEM_RAM, or RETRO_MEMORY_VIDEO_RAM. + * + * @return The size of the region in memory, or 0 when not available. + * + * @see RETRO_MEMORY_SAVE_RAM + * @see RETRO_MEMORY_RTC + * @see RETRO_MEMORY_SYSTEM_RAM + * @see RETRO_MEMORY_VIDEO_RAM + */ +RETRO_API size_t retro_get_memory_size(unsigned id); + +#ifdef __cplusplus +} +#endif + +#endif