diff --git a/platform/libretro/libretro-common/compat/compat_strl.c b/platform/libretro/libretro-common/compat/compat_strl.c index 317231072..3a6392cb1 100644 --- a/platform/libretro/libretro-common/compat/compat_strl.c +++ b/platform/libretro/libretro-common/compat/compat_strl.c @@ -60,10 +60,3 @@ size_t strlcat(char *dest, const char *source, size_t size) return len + strlcpy(dest, source, size); } #endif - -char *strldup(const char *s, size_t n) -{ - char *dst = (char*)malloc(sizeof(char) * (n + 1)); - strlcpy(dst, s, n); - return dst; -} diff --git a/platform/libretro/libretro-common/compat/fopen_utf8.c b/platform/libretro/libretro-common/compat/fopen_utf8.c index 85abb59ef..384657b5d 100644 --- a/platform/libretro/libretro-common/compat/fopen_utf8.c +++ b/platform/libretro/libretro-common/compat/fopen_utf8.c @@ -37,27 +37,28 @@ void *fopen_utf8(const char * filename, const char * mode) { #if defined(LEGACY_WIN32) - FILE *ret = NULL; char * filename_local = utf8_to_local_string_alloc(filename); - - if (!filename_local) - return NULL; - ret = fopen(filename_local, mode); if (filename_local) + { + FILE *ret = fopen(filename_local, mode); free(filename_local); - return ret; + return ret; + } #else - wchar_t * filename_w = utf8_to_utf16_string_alloc(filename); - wchar_t * mode_w = utf8_to_utf16_string_alloc(mode); - FILE* ret = NULL; - - if (filename_w && mode_w) - ret = _wfopen(filename_w, mode_w); + wchar_t * filename_w = utf8_to_utf16_string_alloc(filename); if (filename_w) + { + FILE *ret = NULL; + wchar_t *mode_w = utf8_to_utf16_string_alloc(mode); + if (mode_w) + { + ret = _wfopen(filename_w, mode_w); + free(mode_w); + } free(filename_w); - if (mode_w) - free(mode_w); - return ret; + return ret; + } #endif + return NULL; } #endif diff --git a/platform/libretro/libretro-common/encodings/encoding_utf.c b/platform/libretro/libretro-common/encodings/encoding_utf.c index 2760824d2..f9c594de6 100644 --- a/platform/libretro/libretro-common/encodings/encoding_utf.c +++ b/platform/libretro/libretro-common/encodings/encoding_utf.c @@ -51,9 +51,12 @@ static unsigned leading_ones(uint8_t c) return ones; } -/* Simple implementation. Assumes the sequence is - * properly synchronized and terminated. */ - +/** + * utf8_conv_utf32: + * + * Simple implementation. Assumes the sequence is + * properly synchronized and terminated. + **/ size_t utf8_conv_utf32(uint32_t *out, size_t out_chars, const char *in, size_t in_size) { @@ -79,7 +82,7 @@ size_t utf8_conv_utf32(uint32_t *out, size_t out_chars, for (i = 0; i < extra; i++, in++, shift -= 6) c |= (*in & 0x3f) << shift; - *out++ = c; + *out++ = c; in_size -= 1 + extra; out_chars--; ret++; @@ -88,6 +91,11 @@ size_t utf8_conv_utf32(uint32_t *out, size_t out_chars, return ret; } +/** + * utf16_conv_utf8: + * + * Leaf function. + **/ bool utf16_conv_utf8(uint8_t *out, size_t *out_chars, const uint16_t *in, size_t in_size) { @@ -148,16 +156,20 @@ bool utf16_conv_utf8(uint8_t *out, size_t *out_chars, return false; } -/* Acts mostly like strlcpy. +/** + * utf8cpy: + * + * Acts mostly like strlcpy. * * Copies the given number of UTF-8 characters, - * but at most d_len bytes. + * but at most @d_len bytes. * - * Always NULL terminates. - * Does not copy half a character. + * Always NULL terminates. Does not copy half a character. + * @s is assumed valid UTF-8. + * Use only if @chars is considerably less than @d_len. * - * Returns number of bytes. 's' is assumed valid UTF-8. - * Use only if 'chars' is considerably less than 'd_len'. */ + * @return Number of bytes. + **/ size_t utf8cpy(char *d, size_t d_len, const char *s, size_t chars) { const uint8_t *sb = (const uint8_t*)s; @@ -186,6 +198,11 @@ size_t utf8cpy(char *d, size_t d_len, const char *s, size_t chars) return sb-sb_org; } +/** + * utf8skip: + * + * Leaf function + **/ const char *utf8skip(const char *str, size_t chars) { const uint8_t *strb = (const uint8_t*)str; @@ -204,6 +221,11 @@ const char *utf8skip(const char *str, size_t chars) return (const char*)strb; } +/** + * utf8len: + * + * Leaf function. + **/ size_t utf8len(const char *string) { size_t ret = 0; @@ -220,7 +242,15 @@ size_t utf8len(const char *string) return ret; } -/* Does not validate the input, returns garbage if it's not UTF-8. */ +/** + * utf8_walk: + * + * Does not validate the input. + * + * Leaf function. + * + * @return Returns garbage if it's not UTF-8. + **/ uint32_t utf8_walk(const char **string) { uint8_t first = UTF8_WALKBYTE(string); @@ -248,24 +278,23 @@ static bool utf16_to_char(uint8_t **utf_data, size_t *dest_len, const uint16_t *in) { unsigned len = 0; - while (in[len] != '\0') len++; - utf16_conv_utf8(NULL, dest_len, in, len); *dest_len += 1; - *utf_data = (uint8_t*)malloc(*dest_len); - if (*utf_data == 0) - return false; - - return utf16_conv_utf8(*utf_data, dest_len, in, len); + if ((*utf_data = (uint8_t*)malloc(*dest_len)) != 0) + return utf16_conv_utf8(*utf_data, dest_len, in, len); + return false; } +/** + * utf16_to_char_string: + **/ bool utf16_to_char_string(const uint16_t *in, char *s, size_t len) { - size_t dest_len = 0; - uint8_t *utf16_data = NULL; - bool ret = utf16_to_char(&utf16_data, &dest_len, in); + size_t dest_len = 0; + uint8_t *utf16_data = NULL; + bool ret = utf16_to_char(&utf16_data, &dest_len, in); if (ret) { @@ -274,13 +303,17 @@ bool utf16_to_char_string(const uint16_t *in, char *s, size_t len) } free(utf16_data); - utf16_data = NULL; + utf16_data = NULL; return ret; } #if defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE) -/* Returned pointer MUST be freed by the caller if non-NULL. */ +/** + * mb_to_mb_string_alloc: + * + * @return Returned pointer MUST be freed by the caller if non-NULL. + **/ static char *mb_to_mb_string_alloc(const char *str, enum CodePage cp_in, enum CodePage cp_out) { @@ -300,10 +333,8 @@ static char *mb_to_mb_string_alloc(const char *str, if (!path_buf_wide_len) return strdup(str); - path_buf_wide = (wchar_t*) - calloc(path_buf_wide_len + sizeof(wchar_t), sizeof(wchar_t)); - - if (path_buf_wide) + if ((path_buf_wide = (wchar_t*) + calloc(path_buf_wide_len + sizeof(wchar_t), sizeof(wchar_t)))) { MultiByteToWideChar(cp_in, 0, str, -1, path_buf_wide, path_buf_wide_len); @@ -347,45 +378,49 @@ static char *mb_to_mb_string_alloc(const char *str, } #endif -/* Returned pointer MUST be freed by the caller if non-NULL. */ +/** + * utf8_to_local_string_alloc: + * + * @return Returned pointer MUST be freed by the caller if non-NULL. + **/ char* utf8_to_local_string_alloc(const char *str) { if (str && *str) - { #if defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE) return mb_to_mb_string_alloc(str, CODEPAGE_UTF8, CODEPAGE_LOCAL); #else - /* assume string needs no modification if not on Windows */ - return strdup(str); + return strdup(str); /* Assume string needs no modification if not on Windows */ #endif - } return NULL; } -/* Returned pointer MUST be freed by the caller if non-NULL. */ -char* local_to_utf8_string_alloc(const char *str) +/** + * local_to_utf8_string_alloc: + * + * @return Returned pointer MUST be freed by the caller if non-NULL. + **/ +char *local_to_utf8_string_alloc(const char *str) { - if (str && *str) - { + if (str && *str) #if defined(_WIN32) && !defined(_XBOX) && !defined(UNICODE) - return mb_to_mb_string_alloc(str, CODEPAGE_LOCAL, CODEPAGE_UTF8); + return mb_to_mb_string_alloc(str, CODEPAGE_LOCAL, CODEPAGE_UTF8); #else - /* assume string needs no modification if not on Windows */ - return strdup(str); + return strdup(str); /* Assume string needs no modification if not on Windows */ #endif - } - return NULL; + return NULL; } -/* Returned pointer MUST be freed by the caller if non-NULL. */ +/** + * utf8_to_utf16_string_alloc: + * + * @return Returned pointer MUST be freed by the caller if non-NULL. + **/ wchar_t* utf8_to_utf16_string_alloc(const char *str) { #ifdef _WIN32 int len = 0; - int out_len = 0; #else size_t len = 0; - size_t out_len = 0; #endif wchar_t *buf = NULL; @@ -393,63 +428,55 @@ wchar_t* utf8_to_utf16_string_alloc(const char *str) return NULL; #ifdef _WIN32 - len = MultiByteToWideChar(CP_UTF8, 0, str, -1, NULL, 0); - - if (len) + if ((len = MultiByteToWideChar(CP_UTF8, 0, str, -1, NULL, 0))) { - buf = (wchar_t*)calloc(len, sizeof(wchar_t)); - - if (!buf) + if (!(buf = (wchar_t*)calloc(len, sizeof(wchar_t)))) return NULL; - out_len = MultiByteToWideChar(CP_UTF8, 0, str, -1, buf, len); + if ((MultiByteToWideChar(CP_UTF8, 0, str, -1, buf, len)) < 0) + { + free(buf); + return NULL; + } } else { - /* fallback to ANSI codepage instead */ - len = MultiByteToWideChar(CP_ACP, 0, str, -1, NULL, 0); - - if (len) + /* Fallback to ANSI codepage instead */ + if ((len = MultiByteToWideChar(CP_ACP, 0, str, -1, NULL, 0))) { - buf = (wchar_t*)calloc(len, sizeof(wchar_t)); - - if (!buf) + if (!(buf = (wchar_t*)calloc(len, sizeof(wchar_t)))) return NULL; - out_len = MultiByteToWideChar(CP_ACP, 0, str, -1, buf, len); + if ((MultiByteToWideChar(CP_ACP, 0, str, -1, buf, len)) < 0) + { + free(buf); + return NULL; + } } } - - if (out_len < 0) - { - free(buf); - return NULL; - } #else /* NOTE: For now, assume non-Windows platforms' locale is already UTF-8. */ - len = mbstowcs(NULL, str, 0) + 1; - - if (len) + if ((len = mbstowcs(NULL, str, 0) + 1)) { - buf = (wchar_t*)calloc(len, sizeof(wchar_t)); - - if (!buf) + if (!(buf = (wchar_t*)calloc(len, sizeof(wchar_t)))) return NULL; - out_len = mbstowcs(buf, str, len); - } - - if (out_len == (size_t)-1) - { - free(buf); - return NULL; + if ((mbstowcs(buf, str, len)) == (size_t)-1) + { + free(buf); + return NULL; + } } #endif return buf; } -/* Returned pointer MUST be freed by the caller if non-NULL. */ +/** + * utf16_to_utf8_string_alloc: + * + * @return Returned pointer MUST be freed by the caller if non-NULL. + **/ char* utf16_to_utf8_string_alloc(const wchar_t *str) { #ifdef _WIN32 @@ -465,20 +492,17 @@ char* utf16_to_utf8_string_alloc(const wchar_t *str) #ifdef _WIN32 { UINT code_page = CP_UTF8; - len = WideCharToMultiByte(code_page, - 0, str, -1, NULL, 0, NULL, NULL); /* fallback to ANSI codepage instead */ - if (!len) + if (!(len = WideCharToMultiByte(code_page, + 0, str, -1, NULL, 0, NULL, NULL))) { code_page = CP_ACP; len = WideCharToMultiByte(code_page, 0, str, -1, NULL, 0, NULL, NULL); } - buf = (char*)calloc(len, sizeof(char)); - - if (!buf) + if (!(buf = (char*)calloc(len, sizeof(char)))) return NULL; if (WideCharToMultiByte(code_page, @@ -491,13 +515,9 @@ char* utf16_to_utf8_string_alloc(const wchar_t *str) #else /* NOTE: For now, assume non-Windows platforms' * locale is already UTF-8. */ - len = wcstombs(NULL, str, 0) + 1; - - if (len) + if ((len = wcstombs(NULL, str, 0) + 1)) { - buf = (char*)calloc(len, sizeof(char)); - - if (!buf) + if (!(buf = (char*)calloc(len, sizeof(char)))) return NULL; if (wcstombs(buf, str, len) == (size_t)-1) diff --git a/platform/libretro/libretro-common/file/file_path.c b/platform/libretro/libretro-common/file/file_path.c index c696ff045..902044492 100644 --- a/platform/libretro/libretro-common/file/file_path.c +++ b/platform/libretro/libretro-common/file/file_path.c @@ -71,27 +71,29 @@ /* Time format strings with AM-PM designation require special * handling due to platform dependence */ -void strftime_am_pm(char *s, size_t len, const char* format, +size_t strftime_am_pm(char *s, size_t len, const char* format, const void *ptr) { - char *local = NULL; + size_t _len = 0; +#if !(defined(__linux__) && !defined(ANDROID)) + char *local = NULL; +#endif const struct tm *timeptr = (const struct tm*)ptr; - /* Ensure correct locale is set * > Required for localised AM/PM strings */ setlocale(LC_TIME, ""); - - strftime(s, len, format, timeptr); + _len = strftime(s, len, format, timeptr); #if !(defined(__linux__) && !defined(ANDROID)) if ((local = local_to_utf8_string_alloc(s))) { if (!string_is_empty(local)) - strlcpy(s, local, len); + _len = strlcpy(s, local, len); free(local); local = NULL; } #endif + return _len; } /** @@ -137,13 +139,13 @@ void path_linked_list_add_path(struct path_linked_list *in_path_linked_list, char *path) { /* If the first item does not have a path this is - a list which has just been created, so we just fill + a list which has just been created, so we just fill the path for the first item */ if (!in_path_linked_list->path) in_path_linked_list->path = strdup(path); else - { + { struct path_linked_list *node = (struct path_linked_list*) malloc(sizeof(*node)); if (node) @@ -356,11 +358,7 @@ char *find_last_slash(const char *str) { const char *slash = strrchr(str, '/'); const char *backslash = strrchr(str, '\\'); - - if (!slash || (backslash > slash)) - return (char*)backslash; - else - return (char*)slash; + return (!slash || (backslash > slash)) ? (char*)backslash : (char*)slash; } /** @@ -374,7 +372,9 @@ char *find_last_slash(const char *str) size_t fill_pathname_slash(char *path, size_t size) { size_t path_len; - const char *last_slash = find_last_slash(path); + const char *slash = strrchr(path, '/'); + const char *backslash = strrchr(path, '\\'); + const char *last_slash = (!slash || (backslash > slash)) ? (char*)backslash : (char*)slash; if (!last_slash) return strlcat(path, PATH_DEFAULT_SLASH(), size); path_len = strlen(path); @@ -464,25 +464,32 @@ void fill_pathname_basedir(char *out_dir, bool fill_pathname_parent_dir_name(char *out_dir, const char *in_dir, size_t size) { - char *temp = strdup(in_dir); - char *last = find_last_slash(temp); + char *tmp = strdup(in_dir); + const char *slash = strrchr(tmp, '/'); + const char *backslash = strrchr(tmp, '\\'); + char *last_slash = (!slash || (backslash > slash)) ? (char*)backslash : (char*)slash; - if (last && last[1] == 0) + if (last_slash && last_slash[1] == 0) { - *last = '\0'; - last = find_last_slash(temp); + *last_slash = '\0'; + slash = strrchr(tmp, '/'); + backslash = strrchr(tmp, '\\'); + last_slash = (!slash || (backslash > slash)) ? (char*)backslash : (char*)slash; } /* Cut the last part of the string (the filename) after the slash, leaving the directory name (or nested directory names) only. */ - if (last) - *last = '\0'; - - /* Point in_dir to the address of the last slash. */ - /* If find_last_slash returns NULL, it means there was no slash in temp, - so use temp as-is. */ - if (!(in_dir = find_last_slash(temp))) - in_dir = temp; + if (last_slash) + *last_slash = '\0'; + + /* Point in_dir to the address of the last slash. + * If in_dir is NULL, it means there was no slash in tmp, + * so use tmp as-is. */ + slash = strrchr(tmp, '/'); + backslash = strrchr(tmp, '\\'); + in_dir = (!slash || (backslash > slash)) ? (char*)backslash : (char*)slash; + if (!in_dir) + in_dir = tmp; if (in_dir && in_dir[1]) { @@ -491,11 +498,11 @@ bool fill_pathname_parent_dir_name(char *out_dir, strlcpy(out_dir, in_dir + 1, size); else strlcpy(out_dir, in_dir, size); - free(temp); + free(tmp); return true; } - free(temp); + free(tmp); return false; } @@ -593,17 +600,21 @@ size_t fill_str_dated_filename(char *out_filename, **/ void path_basedir(char *path) { - char *last = NULL; + const char *slash; + const char *backslash; + char *last_slash = NULL; if (!path || path[0] == '\0' || path[1] == '\0') return; - - if ((last = find_last_slash(path))) - last[1] = '\0'; + slash = strrchr(path, '/'); + backslash = strrchr(path, '\\'); + last_slash = (!slash || (backslash > slash)) ? (char*)backslash : (char*)slash; + if (last_slash) + last_slash[1] = '\0'; else { - path[0] = '.'; - path[1] = PATH_DEFAULT_SLASH_C(); - path[2] = '\0'; + path[0] = '.'; + path[1] = PATH_DEFAULT_SLASH_C(); + path[2] = '\0'; } } @@ -620,19 +631,26 @@ void path_parent_dir(char *path, size_t len) { if (!path) return; - + if (len && PATH_CHAR_IS_SLASH(path[len - 1])) { - bool path_was_absolute = path_is_absolute(path); + char *last_slash; + const char *slash; + const char *backslash; + bool was_absolute = path_is_absolute(path); + + path[len - 1] = '\0'; - path[len - 1] = '\0'; + slash = strrchr(path, '/'); + backslash = strrchr(path, '\\'); + last_slash = (!slash || (backslash > slash)) ? (char*)backslash : (char*)slash; - if (path_was_absolute && !find_last_slash(path)) + if (was_absolute && !last_slash) { /* We removed the only slash from what used to be an absolute path. * On Linux, this goes from "/" to an empty string and everything works fine, * but on Windows, we went from C:\ to C:, which is not a valid path and that later - * gets errornously treated as a relative one by path_basedir and returns "./". + * gets erroneously treated as a relative one by path_basedir and returns "./". * What we really wanted is an empty string. */ path[0] = '\0'; return; @@ -653,9 +671,12 @@ const char *path_basename(const char *path) { /* We cut either at the first compression-related hash, * or we cut at the last slash */ - const char *ptr = NULL; + const char *ptr = NULL; + const char *slash = strrchr(path, '/'); + const char *backslash = strrchr(path, '\\'); + char *last_slash = (!slash || (backslash > slash)) ? (char*)backslash : (char*)slash; if ( (ptr = path_get_archive_delim(path)) - || (ptr = find_last_slash(path))) + || (ptr = last_slash)) return ptr + 1; return path; } @@ -673,10 +694,10 @@ const char *path_basename(const char *path) const char *path_basename_nocompression(const char *path) { /* We cut at the last slash */ - const char *last = find_last_slash(path); - if (last) - return last + 1; - return path; + const char *slash = strrchr(path, '/'); + const char *backslash = strrchr(path, '\\'); + char *last_slash = (!slash || (backslash > slash)) ? (char*)backslash : (char*)slash; + return (last_slash) ? (last_slash + 1) : path; } /** @@ -697,12 +718,12 @@ bool path_is_absolute(const char *path) /* Many roads lead to Rome... * Note: Drive letter can only be 1 character long */ return ( string_starts_with_size(path, "\\\\", STRLEN_CONST("\\\\")) - || string_starts_with_size(path + 1, ":/", STRLEN_CONST(":/")) + || string_starts_with_size(path + 1, ":/", STRLEN_CONST(":/")) || string_starts_with_size(path + 1, ":\\", STRLEN_CONST(":\\"))); #elif defined(__wiiu__) || defined(VITA) { - const char *seperator = strchr(path, ':'); - return (seperator && (seperator[1] == '/')); + const char *separator = strchr(path, ':'); + return (separator && (separator[1] == '/')); } #endif } @@ -725,7 +746,7 @@ bool path_is_absolute(const char *path) * Note: Symlinks are only resolved on Unix-likes * Note: The current working dir might not be what you expect, * e.g. on Android it is "/" - * Use of fill_pathname_resolve_relative() should be prefered + * Use of fill_pathname_resolve_relative() should be preferred **/ char *path_resolve_realpath(char *buf, size_t size, bool resolve_symlinks) { @@ -842,7 +863,7 @@ char *path_resolve_realpath(char *buf, size_t size, bool resolve_symlinks) tmp[t++] = *p++; } }while(next < buf_end); - + end: tmp[t] = '\0'; @@ -880,11 +901,11 @@ size_t path_relative_to(char *out, if ( path && base - && path[0] != '\0' + && path[0] != '\0' && path[1] != '\0' && base[0] != '\0' && base[1] != '\0' - && path[1] == ':' + && path[1] == ':' && base[1] == ':' && path[0] != base[0]) return strlcpy(out, path, size); @@ -988,7 +1009,9 @@ size_t fill_pathname_join_special(char *out_path, if (*out_path) { - const char *last_slash = find_last_slash(out_path); + const char *slash = strrchr(out_path, '/'); + const char *backslash = strrchr(out_path, '\\'); + char *last_slash = (!slash || (backslash > slash)) ? (char*)backslash : (char*)slash; if (last_slash) { /* Try to preserve slash type. */ @@ -1058,14 +1081,14 @@ size_t fill_pathname_expand_special(char *out_path, char *app_dir = NULL; if (in_path[0] == '~') { - app_dir = (char*)malloc(PATH_MAX_LENGTH * sizeof(char)); - fill_pathname_home_dir(app_dir, PATH_MAX_LENGTH * sizeof(char)); + app_dir = (char*)malloc(DIR_MAX_LENGTH * sizeof(char)); + fill_pathname_home_dir(app_dir, DIR_MAX_LENGTH * sizeof(char)); } else if (in_path[0] == ':') { - app_dir = (char*)malloc(PATH_MAX_LENGTH * sizeof(char)); + app_dir = (char*)malloc(DIR_MAX_LENGTH * sizeof(char)); app_dir[0] = '\0'; - fill_pathname_application_dir(app_dir, PATH_MAX_LENGTH * sizeof(char)); + fill_pathname_application_dir(app_dir, DIR_MAX_LENGTH * sizeof(char)); } if (app_dir) @@ -1101,8 +1124,8 @@ size_t fill_pathname_abbreviate_special(char *out_path, unsigned i; const char *candidates[3]; const char *notations[3]; - char application_dir[PATH_MAX_LENGTH]; - char home_dir[PATH_MAX_LENGTH]; + char application_dir[DIR_MAX_LENGTH]; + char home_dir[DIR_MAX_LENGTH]; application_dir[0] = '\0'; @@ -1149,6 +1172,45 @@ size_t fill_pathname_abbreviate_special(char *out_path, return strlcpy(out_path, in_path, size); } +/** + * sanitize_path_part: + * + * @path_part : directory or filename + * + * Takes single part of a path eg. single filename + * or directory, and removes any special chars that are + * unavailable. + * + * @returns new string that has been sanitized + **/ +const char *sanitize_path_part(const char *path_part, size_t size) +{ + int i; + int j = 0; + char *tmp = NULL; + const char *special_chars = "<>:\"/\\|?*"; + + if (string_is_empty(path_part)) + return NULL; + + tmp = (char *)malloc((size + 1) * sizeof(char)); + + for (i = 0; path_part[i] != '\0'; i++) + { + /* Check if the current character is + * one of the special characters */ + + /* If not, copy it to the temporary array */ + if (!strchr(special_chars, path_part[i])) + tmp[j++] = path_part[i]; + } + + tmp[j] = '\0'; + + /* Return the new string */ + return tmp; +} + /** * pathname_conform_slashes_to_os: * @@ -1156,7 +1218,7 @@ size_t fill_pathname_abbreviate_special(char *out_path, * * Leaf function. * - * Changes the slashes to the correct kind for the OS + * Changes the slashes to the correct kind for the OS * So forward slash on linux and backslash on Windows **/ void pathname_conform_slashes_to_os(char *path) @@ -1174,7 +1236,7 @@ void pathname_conform_slashes_to_os(char *path) * * Leaf function. * - * Change all slashes to forward so they are more + * Change all slashes to forward so they are more * portable between Windows and Linux **/ void pathname_make_slashes_portable(char *path) @@ -1215,9 +1277,9 @@ static int get_pathname_num_slashes(const char *in_path) /** * fill_pathname_abbreviated_or_relative: * - * Fills the supplied path with either the abbreviated path or + * Fills the supplied path with either the abbreviated path or * the relative path, which ever one has less depth / number of slashes - * + * * If lengths of abbreviated and relative paths are the same, * the relative path will be used * @in_path can be an absolute, relative or abbreviated path @@ -1233,7 +1295,7 @@ size_t fill_pathname_abbreviated_or_relative(char *out_path, char absolute_path[PATH_MAX_LENGTH]; char relative_path[PATH_MAX_LENGTH]; char abbreviated_path[PATH_MAX_LENGTH]; - + expanded_path[0] = '\0'; absolute_path[0] = '\0'; relative_path[0] = '\0'; @@ -1267,7 +1329,7 @@ size_t fill_pathname_abbreviated_or_relative(char *out_path, absolute_path, sizeof(abbreviated_path)); /* Use the shortest path, preferring the relative path*/ - if ( get_pathname_num_slashes(relative_path) <= + if ( get_pathname_num_slashes(relative_path) <= get_pathname_num_slashes(abbreviated_path)) return strlcpy(out_path, relative_path, size); return strlcpy(out_path, abbreviated_path, size); @@ -1282,23 +1344,26 @@ size_t fill_pathname_abbreviated_or_relative(char *out_path, **/ void path_basedir_wrapper(char *path) { - char *last = NULL; + const char *slash; + const char *backslash; + char *last_slash = NULL; if (!path || path[0] == '\0' || path[1] == '\0') return; - #ifdef HAVE_COMPRESSION /* We want to find the directory with the archive in basedir. */ - if ((last = (char*)path_get_archive_delim(path))) - *last = '\0'; + if ((last_slash = (char*)path_get_archive_delim(path))) + *last_slash = '\0'; #endif - - if ((last = find_last_slash(path))) - last[1] = '\0'; + slash = strrchr(path, '/'); + backslash = strrchr(path, '\\'); + last_slash = (!slash || (backslash > slash)) ? (char*)backslash : (char*)slash; + if (last_slash) + last_slash[1] = '\0'; else { - path[0] = '.'; - path[1] = PATH_DEFAULT_SLASH_C(); - path[2] = '\0'; + path[0] = '.'; + path[1] = PATH_DEFAULT_SLASH_C(); + path[2] = '\0'; } } @@ -1348,10 +1413,10 @@ void fill_pathname_application_path(char *s, size_t len) CFStringGetCString(bundle_path, s, len, kCFStringEncodingUTF8); #ifdef HAVE_COCOATOUCH { - /* This needs to be done so that the path becomes + /* This needs to be done so that the path becomes * /private/var/... and this * is used consistently throughout for the iOS bundle path */ - char resolved_bundle_dir_buf[PATH_MAX_LENGTH] = {0}; + char resolved_bundle_dir_buf[DIR_MAX_LENGTH] = {0}; if (realpath(s, resolved_bundle_dir_buf)) { size_t _len = strlcpy(s, resolved_bundle_dir_buf, len - 1); @@ -1364,7 +1429,7 @@ void fill_pathname_application_path(char *s, size_t len) CFRelease(bundle_path); CFRelease(bundle_url); #ifndef HAVE_COCOATOUCH - /* Not sure what this does but it breaks + /* Not sure what this does but it breaks * stuff for iOS, so skipping */ strlcat(s, "nobin", len); #endif @@ -1388,20 +1453,19 @@ void fill_pathname_application_path(char *s, size_t len) free(buff); #else { - pid_t pid; static const char *exts[] = { "exe", "file", "path/a.out" }; char link_path[255]; + pid_t pid = getpid(); + size_t _len = snprintf(link_path, sizeof(link_path), "/proc/%u/", + (unsigned)pid); - link_path[0] = *s = '\0'; - pid = getpid(); + *s = '\0'; /* Linux, BSD and Solaris paths. Not standardized. */ for (i = 0; i < ARRAY_SIZE(exts); i++) { ssize_t ret; - - snprintf(link_path, sizeof(link_path), "/proc/%u/%s", - (unsigned)pid, exts[i]); + strlcpy(link_path + _len, exts[i], sizeof(link_path) - _len); if ((ret = readlink(link_path, s, len - 1)) >= 0) { @@ -1423,7 +1487,7 @@ void fill_pathname_application_dir(char *s, size_t len) #endif } -void fill_pathname_home_dir(char *s, size_t len) +size_t fill_pathname_home_dir(char *s, size_t len) { #ifdef __WINRT__ const char *home = uwp_dir_data; @@ -1431,9 +1495,9 @@ void fill_pathname_home_dir(char *s, size_t len) const char *home = getenv("HOME"); #endif if (home) - strlcpy(s, home, len); - else - *s = 0; + return strlcpy(s, home, len); + *s = 0; + return 0; } #endif diff --git a/platform/libretro/libretro-common/include/compat/fnmatch.h b/platform/libretro/libretro-common/include/compat/fnmatch.h index 978787844..8bdeb2f6a 100644 --- a/platform/libretro/libretro-common/include/compat/fnmatch.h +++ b/platform/libretro/libretro-common/include/compat/fnmatch.h @@ -25,6 +25,11 @@ #define FNM_NOMATCH 1 +/** + * Portable implementation of \c fnmatch(3), + * except \c flags is not implemented. + * @see https://man7.org/linux/man-pages/man3/fnmatch.3.html + */ int rl_fnmatch(const char *pattern, const char *string, int flags); #endif diff --git a/platform/libretro/libretro-common/include/compat/getopt.h b/platform/libretro/libretro-common/include/compat/getopt.h index 48603f0d2..3647f2e5c 100644 --- a/platform/libretro/libretro-common/include/compat/getopt.h +++ b/platform/libretro/libretro-common/include/compat/getopt.h @@ -27,9 +27,17 @@ #include "../../../config.h" #endif -/* Custom implementation of the GNU getopt_long for portability. - * Not designed to be fully compatible, but compatible with - * the features RetroArch uses. */ +/** + * @file getopt.h + * + * Portable reimplementation of a subset of libc's \c getopt_long. + * Not designed to be fully compatible, + * but it's enough for RetroArch's purposes. + * + * If \c getopt_long is available (as determined by \c HAVE_GETOPT_LONG), it will be used instead. + * + * @see https://man7.org/linux/man-pages/man3/getopt.3.html + */ #ifdef HAVE_GETOPT_LONG #include diff --git a/platform/libretro/libretro-common/include/compat/ifaddrs.h b/platform/libretro/libretro-common/include/compat/ifaddrs.h index 2dc68487e..43546742b 100644 --- a/platform/libretro/libretro-common/include/compat/ifaddrs.h +++ b/platform/libretro/libretro-common/include/compat/ifaddrs.h @@ -47,7 +47,20 @@ struct ifaddrs #include +/** + * Portable reimplementation of \c getifaddrs(). + * The original function will be used if it's available. + * + * @see https://man7.org/linux/man-pages/man3/getifaddrs.3.html + */ extern int getifaddrs(struct ifaddrs **ifap); + +/** + * Portable reimplementation of \c freeifaddrs(). + * The original function will be used if it's available. + * + * @see https://man7.org/linux/man-pages/man3/getifaddrs.3.html + */ extern void freeifaddrs(struct ifaddrs *ifa); #endif diff --git a/platform/libretro/libretro-common/include/compat/intrinsics.h b/platform/libretro/libretro-common/include/compat/intrinsics.h index ac490274e..bc100f834 100644 --- a/platform/libretro/libretro-common/include/compat/intrinsics.h +++ b/platform/libretro/libretro-common/include/compat/intrinsics.h @@ -38,7 +38,13 @@ RETRO_BEGIN_DECLS -/* Count Leading Zero, unsigned 16bit input value */ +/** + * Counts the leading zero bits in a \c uint16_t. + * Uses compiler intrinsics if available, or a standard C implementation if not. + * + * @param val Value to count leading zeroes in. + * @return Number of leading zeroes in \c val. + */ static INLINE unsigned compat_clz_u16(uint16_t val) { #if defined(__GNUC__) @@ -56,7 +62,13 @@ static INLINE unsigned compat_clz_u16(uint16_t val) #endif } -/* Count Trailing Zero */ +/** + * Counts the trailing zero bits in a \c uint16_t. + * Uses compiler intrinsics if available, or a standard C implementation if not. + * + * @param val Value to count trailing zeroes in. + * @return Number of trailing zeroes in \c val. + */ static INLINE int compat_ctz(unsigned x) { #if defined(__GNUC__) && !defined(RARCH_CONSOLE) diff --git a/platform/libretro/libretro-common/include/compat/posix_string.h b/platform/libretro/libretro-common/include/compat/posix_string.h index 47964b2a0..661481877 100644 --- a/platform/libretro/libretro-common/include/compat/posix_string.h +++ b/platform/libretro/libretro-common/include/compat/posix_string.h @@ -25,31 +25,64 @@ #include +/** + * @file posix_string.h + * + * Portable reimplementations of various string functions + * that are normally provided by libc or POSIX. + */ + #ifdef _MSC_VER #include #endif RETRO_BEGIN_DECLS -#ifdef _WIN32 +#if defined(_WIN32) || defined(DOXYGEN) #undef strtok_r #define strtok_r(str, delim, saveptr) retro_strtok_r__(str, delim, saveptr) +/** + * Portable reimplementation of \c strtok_r(). + * The original function will be used if it's available. + * + * @see https://man7.org/linux/man-pages/man3/strtok.3.html + */ char *strtok_r(char *str, const char *delim, char **saveptr); #endif -#ifdef _MSC_VER +#if defined(_MSC_VER) || defined(DOXYGEN) #undef strcasecmp #undef strdup + #define strcasecmp(a, b) retro_strcasecmp__(a, b) #define strdup(orig) retro_strdup__(orig) +/** + * Portable reimplementation of \c strcasecmp(). + * The original function will be used if it's available. + * + * @see https://man7.org/linux/man-pages/man3/strcasecmp.3.html + */ int strcasecmp(const char *a, const char *b); + +/** + * Portable reimplementation of \c strdup(). + * The original function will be used if it's available. + * + * @see https://man7.org/linux/man-pages/man3/strdup.3.html + */ char *strdup(const char *orig); /* isblank is available since MSVC 2013 */ #if _MSC_VER < 1800 #undef isblank #define isblank(c) retro_isblank__(c) +/** + * Portable reimplementation of \c isblank(). + * The original function will be used if it's available. + * + * @see https://en.cppreference.com/w/c/string/byte/isblank + */ int isblank(int c); #endif diff --git a/platform/libretro/libretro-common/include/compat/strcasestr.h b/platform/libretro/libretro-common/include/compat/strcasestr.h index 227e253e7..27b229bc2 100644 --- a/platform/libretro/libretro-common/include/compat/strcasestr.h +++ b/platform/libretro/libretro-common/include/compat/strcasestr.h @@ -39,6 +39,14 @@ RETRO_BEGIN_DECLS * since we prefer to use the actual name. */ #define strcasestr(haystack, needle) strcasestr_retro__(haystack, needle) +/** + * Portable reimplementation of \c strcasestr(3). + * If the original function is available + * (as determined by the presence of \c HAVE_STRCASESTR), + * it will be used instead. + * + * @see https://man7.org/linux/man-pages/man3/strstr.3.html + */ char *strcasestr(const char *haystack, const char *needle); RETRO_END_DECLS diff --git a/platform/libretro/libretro-common/include/compat/strl.h b/platform/libretro/libretro-common/include/compat/strl.h index 5e7a892fc..dfa4f1098 100644 --- a/platform/libretro/libretro-common/include/compat/strl.h +++ b/platform/libretro/libretro-common/include/compat/strl.h @@ -23,6 +23,15 @@ #ifndef __LIBRETRO_SDK_COMPAT_STRL_H #define __LIBRETRO_SDK_COMPAT_STRL_H +/** + * @file strl.h + * + * Portable implementation of \c strlcpy(3) and \c strlcat(3). + * If these functions are available on the target platform, + * then the originals should be imported instead. + * + * @see https://linux.die.net/man/3/strlcpy + */ #include #include @@ -47,11 +56,29 @@ RETRO_BEGIN_DECLS #define strlcat(dst, src, size) strlcat_retro__(dst, src, size) +/** + * @brief Portable implementation of \c strlcpy(3). + * @see https://linux.die.net/man/3/strlcpy + */ size_t strlcpy(char *dest, const char *source, size_t size); + +/** + * @brief Portable implementation of \c strlcat(3). + * @see https://linux.die.net/man/3/strlcpy + */ size_t strlcat(char *dest, const char *source, size_t size); #endif +/** + * A version of \c strndup(3) that guarantees the result will be null-terminated. + * + * @param s The string to duplicate. + * @param n The maximum number of characters to copy from \c s. + * The result will allocate one more byte than this value. + * @return Pointer to the cloned string. + * Must be freed with \c free(). + */ char *strldup(const char *s, size_t n); RETRO_END_DECLS diff --git a/platform/libretro/libretro-common/include/encodings/utf.h b/platform/libretro/libretro-common/include/encodings/utf.h index bea4e145d..ccd08fa6e 100644 --- a/platform/libretro/libretro-common/include/encodings/utf.h +++ b/platform/libretro/libretro-common/include/encodings/utf.h @@ -38,29 +38,99 @@ enum CodePage CODEPAGE_UTF8 = 65001 /* CP_UTF8 */ }; +/** + * utf8_conv_utf32: + * + * Simple implementation. Assumes the sequence is + * properly synchronized and terminated. + **/ size_t utf8_conv_utf32(uint32_t *out, size_t out_chars, const char *in, size_t in_size); +/** + * utf16_conv_utf8: + * + * Leaf function. + **/ bool utf16_conv_utf8(uint8_t *out, size_t *out_chars, const uint16_t *in, size_t in_size); +/** + * utf8len: + * + * Leaf function. + **/ size_t utf8len(const char *string); +/** + * utf8cpy: + * + * Acts mostly like strlcpy. + * + * Copies the given number of UTF-8 characters, + * but at most @d_len bytes. + * + * Always NULL terminates. Does not copy half a character. + * @s is assumed valid UTF-8. + * Use only if @chars is considerably less than @d_len. + * + * Hidden non-leaf function cost: + * - Calls memcpy + * + * @return Number of bytes. + **/ size_t utf8cpy(char *d, size_t d_len, const char *s, size_t chars); +/** + * utf8skip: + * + * Leaf function + **/ const char *utf8skip(const char *str, size_t chars); +/** + * utf8_walk: + * + * Does not validate the input. + * + * Leaf function. + * + * @return Returns garbage if it's not UTF-8. + **/ uint32_t utf8_walk(const char **string); +/** + * utf16_to_char_string: + **/ bool utf16_to_char_string(const uint16_t *in, char *s, size_t len); -char* utf8_to_local_string_alloc(const char *str); - -char* local_to_utf8_string_alloc(const char *str); - -wchar_t* utf8_to_utf16_string_alloc(const char *str); +/** + * utf8_to_local_string_alloc: + * + * @return Returned pointer MUST be freed by the caller if non-NULL. + **/ +char *utf8_to_local_string_alloc(const char *str); -char* utf16_to_utf8_string_alloc(const wchar_t *str); +/** + * local_to_utf8_string_alloc: + * + * @return Returned pointer MUST be freed by the caller if non-NULL. + **/ +char *local_to_utf8_string_alloc(const char *str); + +/** + * utf8_to_utf16_string_alloc: + * + * @return Returned pointer MUST be freed by the caller if non-NULL. + **/ +wchar_t *utf8_to_utf16_string_alloc(const char *str); + +/** + * utf16_to_utf8_string_alloc: + * + * @return Returned pointer MUST be freed by the caller if non-NULL. + **/ +char *utf16_to_utf8_string_alloc(const wchar_t *str); RETRO_END_DECLS diff --git a/platform/libretro/libretro-common/include/file/file_path.h b/platform/libretro/libretro-common/include/file/file_path.h index d410cc43b..88ebde2ea 100644 --- a/platform/libretro/libretro-common/include/file/file_path.h +++ b/platform/libretro/libretro-common/include/file/file_path.h @@ -68,7 +68,7 @@ void path_linked_list_free(struct path_linked_list *in_path_linked_list); /** * Add a node to the linked list with this path - * If the first node's path if it's not yet set, + * If the first node's path if it's not yet set, * set this instead **/ void path_linked_list_add_path(struct path_linked_list *in_path_linked_list, char *path); @@ -222,7 +222,7 @@ void path_parent_dir(char *path, size_t len); * Note: Symlinks are only resolved on Unix-likes * Note: The current working dir might not be what you expect, * e.g. on Android it is "/" - * Use of fill_pathname_resolve_relative() should be prefered + * Use of fill_pathname_resolve_relative() should be preferred **/ char *path_resolve_realpath(char *buf, size_t size, bool resolve_symlinks); @@ -342,7 +342,7 @@ size_t fill_str_dated_filename(char *out_filename, * a backslash on Windows too which takes precedence * over regular slash. - * Hidden non-leaf function cost: + * Hidden non-leaf function cost: * - calls strrchr * * @return pointer to last slash/backslash found in @str. @@ -468,8 +468,8 @@ void fill_pathname_resolve_relative(char *out_path, const char *in_refpath, * Joins a directory (@dir) and path (@path) together. * Makes sure not to get two consecutive slashes * between directory and path. - * - * Hidden non-leaf function cost: + * + * Hidden non-leaf function cost: * - calls strlcpy at least once * - calls fill_pathname_slash() * @@ -497,7 +497,7 @@ size_t fill_pathname_join(char *out_path, const char *dir, * Makes sure not to get two consecutive slashes * between directory and path. * - * Hidden non-leaf function cost: + * Hidden non-leaf function cost: * - calls strlcpy 2x * - calls find_last_slash() * @@ -522,7 +522,7 @@ size_t fill_pathname_join_special_ext(char *out_path, * Joins a directory (@dir) and path (@path) together * using the given delimiter (@delim). * - * Hidden non-leaf function cost: + * Hidden non-leaf function cost: * - can call strlen * - can call strlcpy * - can call strlcat @@ -539,9 +539,9 @@ size_t fill_pathname_abbreviate_special(char *out_path, /** * fill_pathname_abbreviated_or_relative: * - * Fills the supplied path with either the abbreviated path or + * Fills the supplied path with either the abbreviated path or * the relative path, which ever one has less depth / number of slashes - * + * * If lengths of abbreviated and relative paths are the same, * the relative path will be used * @in_path can be an absolute, relative or abbreviated path @@ -551,14 +551,28 @@ size_t fill_pathname_abbreviate_special(char *out_path, size_t fill_pathname_abbreviated_or_relative(char *out_path, const char *in_refpath, const char *in_path, size_t size); +/** + * sanitize_path_part: + * + * @path_part : directory or filename + * @size : length of path_part + * + * Takes single part of a path eg. single filename + * or directory, and removes any special chars that are + * unavailable. + * + * @returns new string that has been sanitized + **/ +const char *sanitize_path_part(const char *path_part, size_t size); + /** * pathname_conform_slashes_to_os: * * @path : path - * + * * Leaf function. * - * Changes the slashes to the correct kind for the os + * Changes the slashes to the correct kind for the os * So forward slash on linux and backslash on Windows **/ void pathname_conform_slashes_to_os(char *path); @@ -569,7 +583,7 @@ void pathname_conform_slashes_to_os(char *path); * * Leaf function. * - * Change all slashes to forward so they are more + * Change all slashes to forward so they are more * portable between Windows and Linux **/ void pathname_make_slashes_portable(char *path); @@ -620,7 +634,7 @@ void path_basedir_wrapper(char *path); * Assumes path is a directory. Appends a slash * if not already there. - * Hidden non-leaf function cost: + * Hidden non-leaf function cost: * - calls find_last_slash() * - can call strlcat once if it returns false * - calls strlen @@ -630,7 +644,7 @@ size_t fill_pathname_slash(char *path, size_t size); #if !defined(RARCH_CONSOLE) && defined(RARCH_INTERNAL) void fill_pathname_application_path(char *buf, size_t size); void fill_pathname_application_dir(char *buf, size_t size); -void fill_pathname_home_dir(char *buf, size_t size); +size_t fill_pathname_home_dir(char *buf, size_t size); #endif /** @@ -663,8 +677,10 @@ bool path_mkdir(const char *dir); bool path_is_directory(const char *path); /* Time format strings with AM-PM designation require special - * handling due to platform dependence */ -void strftime_am_pm(char *s, size_t len, const char* format, + * handling due to platform dependence + * @return Length of the string written to @s + */ +size_t strftime_am_pm(char *s, size_t len, const char* format, const void* timeptr); bool path_is_character_special(const char *path); diff --git a/platform/libretro/libretro-common/include/libretro.h b/platform/libretro/libretro-common/include/libretro.h index 72e642578..288512b91 100644 --- a/platform/libretro/libretro-common/include/libretro.h +++ b/platform/libretro/libretro-common/include/libretro.h @@ -1,8 +1,15 @@ -/* Copyright (C) 2010-2020 The RetroArch team +/*! + * 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"), @@ -69,7 +76,7 @@ extern "C" { # endif # endif # else -# if defined(__GNUC__) && __GNUC__ >= 4 && !defined(__PS3__) +# if defined(__GNUC__) && __GNUC__ >= 4 # define RETRO_API RETRO_CALLCONV __attribute__((__visibility__("default"))) # else # define RETRO_API RETRO_CALLCONV @@ -77,78 +84,185 @@ extern "C" { # endif #endif -/* Used for checking API/ABI mismatches that can break libretro - * implementations. - * It is not incremented for compatible changes to the API. +/** + * 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 -/* - * Libretro's fundamental device abstractions. - * - * Libretro's input system consists of some standardized device types, - * such as a joypad (with/without analog), mouse, keyboard, lightgun - * and a pointer. +/** + * @defgroup RETRO_DEVICE Input Devices + * @brief Libretro's fundamental device abstractions. * - * The functionality of these devices are fixed, and individual cores - * 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, and not having to worry about binding input - * correctly to arbitrary controller layouts. + * 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) -/* Input disabled. */ +/** + * @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 -/* The JOYPAD is called RetroPad. It is essentially a Super Nintendo - * controller, but with additional L2/R2/L3/R3 buttons, similar to a - * PS1 DualShock. */ +/** + * 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 -/* The mouse is a simple mouse, similar to Super Nintendo's mouse. - * X and Y coordinates are reported relatively to last poll (poll callback). - * It is up to the libretro implementation to keep track of where the mouse - * pointer is supposed to be on the screen. - * The frontend must make sure not to interfere with its own hardware - * mouse pointer. +/** + * 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 -/* KEYBOARD device lets one poll for raw key pressed. - * It is poll based, so input callback will return with the current - * pressed state. - * For event/text based keyboard input, see - * RETRO_ENVIRONMENT_SET_KEYBOARD_CALLBACK. +/** + * 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 -/* LIGHTGUN device is similar to Guncon-2 for PlayStation 2. - * It reports X/Y coordinates in screen space (similar to the pointer) - * in the range [-0x8000, 0x7fff] in both axes, with zero being center and - * -0x8000 being out of bounds. - * As well as reporting on/off screen state. It features a trigger, - * start/select buttons, auxiliary action buttons and a - * directional pad. A forced off-screen shot can be requested for - * auto-reloading function in some games. +/** + * An abstraction around a light gun, similar 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 -/* The ANALOG device is an extension to JOYPAD (RetroPad). - * Similar to DualShock2 it adds two analog sticks and all buttons can - * be analog. This is treated as a separate device type as it returns - * axis values in the full analog range of [-0x7fff, 0x7fff], - * although some devices may return -0x8000. - * Positive X axis is right. Positive Y axis is down. - * Buttons are returned in the range [0, 0x7fff]. - * Only use ANALOG type when polling for analog values. +/** + * 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 -/* Abstracts the concept of a pointing mechanism, e.g. touch. +/** + * 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 @@ -165,45 +279,109 @@ extern "C" { * game image, etc. * * To check if the pointer coordinates are valid (e.g. a touch display - * actually being touched), PRESSED returns 1 or 0. + * actually being touched), \c RETRO_DEVICE_ID_POINTER_PRESSED returns 1 or 0. * - * If using a mouse on a desktop, PRESSED will usually correspond to the - * left mouse button, but this is a frontend decision. - * PRESSED will only return 1 if the pointer is inside the game screen. + * 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 _PRESSED, coordinates can be extracted - * with _X, _Y for index = 0. One can then query _PRESSED, _X, _Y with + * 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 _PRESSED will return false for an index. No further presses - * are registered at this point. */ + * 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 -/* Buttons for the RetroPad (JOYPAD). - * The placement of these is equivalent to placements on the - * Super Nintendo controller. - * L2/R2/L3/R3 buttons correspond to the PS1 DualShock. - * Also used as id values for RETRO_DEVICE_INDEX_ANALOG_BUTTON */ +/** @} */ + +/** @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 @@ -211,6 +389,8 @@ extern "C" { #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 @@ -252,11 +432,16 @@ extern "C" { #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 -/* Id values for LANGUAGE */ +/** + * Identifiers for supported languages. + * @see RETRO_ENVIRONMENT_GET_LANGUAGE + */ enum retro_language { RETRO_LANGUAGE_ENGLISH = 0, @@ -286,12 +471,24 @@ enum retro_language 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, - /* Ensure sizeof(enum) == sizeof(int) */ + /** 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. @@ -316,6 +513,8 @@ enum retro_language /* 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 { @@ -467,6 +666,25 @@ enum retro_key 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) */ @@ -488,916 +706,1467 @@ enum retro_mod RETROKMOD_DUMMY = INT_MAX /* Ensure sizeof(enum) == sizeof(int) */ }; -/* If set, this call is not part of the public libretro API yet. It can - * change or be removed at any time. */ +/** + * @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 -/* Environment callback to be used internally in frontend. */ + +/** Frontend-internal environment callbacks should include this bit. */ #define RETRO_ENVIRONMENT_PRIVATE 0x20000 /* Environment commands. */ -#define RETRO_ENVIRONMENT_SET_ROTATION 1 /* const unsigned * -- - * Sets screen rotation of graphics. - * Valid values are 0, 1, 2, 3, which rotates screen by 0, 90, 180, - * 270 degrees counter-clockwise respectively. - */ -#define RETRO_ENVIRONMENT_GET_OVERSCAN 2 /* bool * -- - * NOTE: As of 2019 this callback is considered deprecated in favor of - * using core options to manage overscan in a more nuanced, core-specific way. - * - * Boolean value whether or not the implementation should use overscan, - * or crop away overscan. - */ -#define RETRO_ENVIRONMENT_GET_CAN_DUPE 3 /* bool * -- - * Boolean value whether or not frontend supports frame duping, - * passing NULL to video frame callback. - */ +/** + * 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 - /* Environ 4, 5 are no longer supported (GET_VARIABLE / SET_VARIABLES), - * and reserved to avoid possible ABI clash. - */ +/** + * 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 -#define RETRO_ENVIRONMENT_SET_MESSAGE 6 /* const struct retro_message * -- - * Sets a message to be displayed in implementation-specific manner - * for a certain amount of 'frames'. - * Should not be used for trivial messages, which should simply be - * logged via RETRO_ENVIRONMENT_GET_LOG_INTERFACE (or as a - * fallback, stderr). - */ -#define RETRO_ENVIRONMENT_SHUTDOWN 7 /* N/A (NULL) -- - * Requests the frontend to shutdown. - * Should only be used if game has a specific - * way to shutdown the game from a menu item or similar. - */ +/** + * 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 - /* const unsigned * -- - * Gives a hint to the frontend how demanding this implementation - * is on a system. E.g. reporting a level of 2 means - * this implementation should run decently on all frontends - * of level 2 and up. - * - * 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 certain games an implementation can play might be - * particularly demanding. - * If called, it should be called in retro_load_game(). - */ + +/** + * 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 - /* const char ** -- - * Returns the "system" directory of the frontend. - * This directory can be used to store system specific - * content such as BIOSes, configuration data, etc. - * The returned value can be NULL. - * If so, no such directory is defined, - * and it's up to the implementation to find a suitable directory. - * - * NOTE: Some cores used this folder also for "save" data such as - * memory cards, etc, for lack of a better place to put it. - * This is now discouraged, and if possible, cores should try to - * use the new GET_SAVE_DIRECTORY. - */ + +/** + * 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 - /* const enum retro_pixel_format * -- - * Sets the internal pixel format used by the implementation. - * The default pixel format is RETRO_PIXEL_FORMAT_0RGB1555. - * This pixel format however, is deprecated (see enum retro_pixel_format). - * If the call returns false, the frontend does not support this pixel - * format. - * - * This function should be called inside retro_load_game() or - * retro_get_system_av_info(). - */ + +/** + * 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 - /* const struct retro_input_descriptor * -- - * Sets an array of retro_input_descriptors. - * It is up to the frontend to present this in a usable way. - * The array is terminated by retro_input_descriptor::description - * being set to NULL. - * This function can be called at any time, but it is recommended - * to call it as early as possible. - */ + +/** + * 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 - /* const struct retro_keyboard_callback * -- - * Sets a callback function used to notify core about keyboard events. - */ + +/** + * 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 - /* const struct retro_disk_control_callback * -- - * Sets an interface which frontend can use to eject and insert - * disk images. - * This is used for games which consist of multiple images and - * must be manually swapped out by the user (e.g. PSX). - */ + +/** + * 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 - /* struct retro_hw_render_callback * -- - * Sets an interface to let a libretro core render with - * hardware acceleration. - * Should be called in retro_load_game(). - * If successful, libretro cores will be able to render to a - * frontend-provided framebuffer. - * The size of this framebuffer will be at least as large as - * max_width/max_height provided in get_av_info(). - * If HW rendering is used, pass only RETRO_HW_FRAME_BUFFER_VALID or - * NULL to retro_video_refresh_t. - */ + +/** + * 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 - /* struct retro_variable * -- - * Interface to acquire user-defined information from environment - * that cannot feasibly be supported in a multi-system way. - * 'key' should be set to a key which has already been set by - * SET_VARIABLES. - * 'data' will be set to a value or NULL. - */ + +/** + * 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 - /* const struct retro_variable * -- - * Allows an implementation to signal the environment - * which variables it might want to check for later using - * GET_VARIABLE. - * This allows the frontend to present these variables to - * a user dynamically. - * This should be called the first time as early as - * possible (ideally in retro_set_environment). - * Afterward it may be called again for the core to communicate - * updated options to the frontend, but the number of core - * options must not change from the number in the initial call. - * - * 'data' points to an array of retro_variable structs - * terminated by a { NULL, NULL } element. - * retro_variable::key should be namespaced to not collide - * with other implementations' keys. E.g. A core called - * 'foo' should use keys named as 'foo_option'. - * retro_variable::value should contain a human readable - * description of the key as well as a '|' delimited list - * of expected values. - * - * The number of possible options should be very limited, - * i.e. it should be feasible to cycle through options - * without a keyboard. - * - * First entry should be treated as a default. - * - * Example entry: - * { "foo_option", "Speed hack coprocessor X; false|true" } - * - * Text before first ';' is description. This ';' must be - * followed by a space, and followed by a list of possible - * values split up with '|'. - * - * Only strings are operated on. The possible values will - * generally be displayed and stored as-is by the frontend. - */ + +/** + * 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 - /* bool * -- - * Result is set to true if some variables are updated by - * frontend since last call to RETRO_ENVIRONMENT_GET_VARIABLE. - * Variables should be queried with GET_VARIABLE. - */ + +/** + * 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 - /* const bool * -- - * If true, the libretro implementation supports calls to - * retro_load_game() with NULL as argument. - * Used by cores which can run without particular game data. - * This should be called within retro_set_environment() only. - */ + +/** + * 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 - /* const char ** -- - * Retrieves the absolute path from where this libretro - * implementation was loaded. - * NULL is returned if the libretro was loaded statically - * (i.e. linked statically to frontend), or if the path cannot be - * determined. - * Mostly useful in cooperation with SET_SUPPORT_NO_GAME as assets can - * be loaded without ugly hacks. - */ - /* Environment 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. */ +/* 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 - /* const struct retro_frame_time_callback * -- - * Lets the core know how much time has passed since last - * invocation of retro_run(). - * The frontend can tamper with the timing to fake fast-forward, - * slow-motion, frame stepping, etc. - * In this case the delta time will use the reference value - * in frame_time_callback.. - */ + +/** + * 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 continuously 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 - /* const struct retro_audio_callback * -- - * Sets an interface which is used to notify a libretro core about audio - * being available for writing. - * The callback can be called from any thread, so a core using this must - * have a thread safe audio implementation. - * It is intended for games where audio and video are completely - * asynchronous and audio can be generated on the fly. - * This interface is not recommended for use with emulators which have - * highly synchronous audio. - * - * 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 implementation. - * Generally, the audio callback will be called continously in a loop. - * - * Due to thread safety guarantees and lack of sync between audio and - * video, a frontend can selectively disallow this interface based on - * internal configuration. A core using this interface must also - * implement the "normal" audio interface. - * - * A libretro core using SET_AUDIO_CALLBACK should also make use of - * SET_FRAME_TIME_CALLBACK. - */ + +/** + * 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 - /* struct retro_rumble_interface * -- - * Gets an interface which is used by a libretro core to set - * state of rumble motors in controllers. - * A strong and weak motor is supported, and they can be - * controlled indepedently. - * Should be called from either retro_init() or retro_load_game(). - * Should not be called from retro_set_environment(). - * Returns false if rumble functionality is unavailable. - */ + +/** + * 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 - /* uint64_t * -- - * Gets a bitmask telling which device type are expected to be - * handled properly in a call to retro_input_state_t. - * Devices which are not handled or recognized always return - * 0 in retro_input_state_t. - * Example bitmask: caps = (1 << RETRO_DEVICE_JOYPAD) | (1 << RETRO_DEVICE_ANALOG). - * Should only be called in retro_run(). - */ + +/** + * 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) - /* struct retro_sensor_interface * -- - * Gets access to the sensor interface. - * The purpose of this interface is to allow - * setting state related to sensors such as polling rate, - * enabling/disable it entirely, etc. - * Reading sensor state is done via the normal - * input_state_callback API. - */ + +/** + * 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) - /* struct retro_camera_callback * -- - * Gets an interface to a video camera driver. - * A libretro core can use this interface to get access to a - * video camera. - * New video frames are delivered in a callback in same - * thread as retro_run(). - * - * GET_CAMERA_INTERFACE should be called in retro_load_game(). - * - * Depending on the camera implementation used, camera frames - * will be delivered as a raw framebuffer, - * or as an OpenGL texture directly. - * - * The core has to tell the frontend here which types of - * buffers can be handled properly. - * An OpenGL texture can only be handled when using a - * libretro GL core (SET_HW_RENDER). - * It is recommended to use a libretro GL core when - * using camera interface. - * - * The camera is not started automatically. The retrieved start/stop - * functions must be used to explicitly - * start and stop the camera driver. - */ + +/** + * 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 - /* struct retro_log_callback * -- - * Gets an interface for logging. This is useful for - * logging in a cross-platform way - * as certain platforms cannot use stderr for logging. - * It also allows the frontend to - * show logging information in a more suitable way. - * If this interface is not used, libretro cores should - * log to stderr as desired. - */ + +/** + * 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 - /* struct retro_perf_callback * -- - * Gets an interface for performance counters. This is useful - * for performance logging in a cross-platform way and for detecting - * architecture-specific features, such as SIMD support. - */ + +/** + * 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 - /* struct retro_location_callback * -- - * Gets access to the location interface. - * The purpose of this interface is to be able to retrieve - * location-based information from the host device, - * such as current latitude / longitude. - */ -#define RETRO_ENVIRONMENT_GET_CONTENT_DIRECTORY 30 /* Old name, kept for compatibility. */ + +/** + * @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 - /* const char ** -- - * Returns the "core assets" directory of the frontend. - * This directory can be used to store specific assets that the - * core relies upon, such as art assets, - * input data, etc etc. - * The returned value can be NULL. - * If so, no such directory is defined, - * and it's up to the implementation to find a suitable directory. - */ + +/** + * 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 - /* const char ** -- - * Returns the "save" directory of the frontend, unless there is no - * save directory available. The save directory should be used to - * store SRAM, memory cards, high scores, etc, if the libretro core - * cannot use the regular memory interface (retro_get_memory_data()). - * - * If the frontend cannot designate a save directory, it will return - * NULL to indicate that the core should attempt to operate without a - * save directory set. - * - * NOTE: early libretro cores used the system directory for save - * files. Cores that need to be backwards-compatible can still check - * GET_SYSTEM_DIRECTORY. - */ -#define RETRO_ENVIRONMENT_SET_SYSTEM_AV_INFO 32 - /* const struct retro_system_av_info * -- - * Sets a new av_info structure. This can only be called from - * within retro_run(). - * This should *only* be used if the core is completely altering the - * internal resolutions, aspect ratios, timings, sampling rate, etc. - * Calling this can require a full reinitialization of video/audio - * drivers in the frontend, - * - * so it is important to call it very sparingly, and usually only with - * the users explicit consent. - * An eventual driver reinitialize will happen so that video and - * audio callbacks - * happening after this call within the same retro_run() call will - * target the newly initialized driver. - * - * This callback makes it possible to support configurable resolutions - * in games, which can be useful to - * avoid setting the "worst case" in max_width/max_height. - * - * ***HIGHLY RECOMMENDED*** Do not call this callback every time - * resolution changes in an emulator core if it's - * expected to be a temporary change, for the reasons of possible - * driver reinitialization. - * This call is not a free pass for not trying to provide - * correct values in retro_get_system_av_info(). If you need to change - * things like aspect ratio or nominal width/height, - * use RETRO_ENVIRONMENT_SET_GEOMETRY, which is a softer variant - * of SET_SYSTEM_AV_INFO. - * - * If this returns false, the frontend does not acknowledge a - * changed av_info struct. - */ + +/** + * 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 for + * 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 - /* const struct retro_get_proc_address_interface * -- - * Allows a libretro core to announce support for the - * get_proc_address() interface. - * This interface allows for a standard way to extend libretro where - * use of environment calls are too indirect, - * e.g. for cases where the frontend wants to call directly into the core. - * - * If a core wants to expose this interface, SET_PROC_ADDRESS_CALLBACK - * **MUST** be called from within retro_set_environment(). - */ + +/** + * 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 - /* const struct retro_subsystem_info * -- - * This environment call introduces the concept of libretro "subsystems". - * A subsystem is a variant of a libretro core which supports - * different kinds of games. - * The purpose of this is to support e.g. emulators which might - * have special needs, e.g. Super Nintendo's Super GameBoy, Sufami Turbo. - * It can also be used to pick among subsystems in an explicit way - * if the libretro implementation is a multi-system emulator itself. - * - * Loading a game via a subsystem is done with retro_load_game_special(), - * and this environment call allows a libretro core to expose which - * subsystems are supported for use with retro_load_game_special(). - * A core passes an array of retro_game_special_info which is terminated - * with a zeroed out retro_game_special_info struct. - * - * If a core wants to use this functionality, SET_SUBSYSTEM_INFO - * **MUST** be called from within retro_set_environment(). - */ + +/** + * 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 - /* const struct retro_controller_info * -- - * This environment call lets a libretro core tell the frontend - * which controller subclasses are recognized in calls to - * retro_set_controller_port_device(). - * - * Some emulators such as Super Nintendo support multiple lightgun - * types which must be specifically selected from. It is therefore - * sometimes necessary for a frontend to be able to tell the core - * about a special kind of input device which is not specifcally - * provided by the Libretro API. - * - * In order for a frontend to understand the workings of those devices, - * they must be defined as a specialized subclass of the generic device - * types already defined in the libretro API. - * - * The core must pass an array of const struct retro_controller_info which - * is terminated with a blanked out struct. Each element of the - * retro_controller_info struct corresponds to the ascending port index - * that is passed to retro_set_controller_port_device() when that function - * is called to indicate to the core that the frontend has changed the - * active device subclass. SEE ALSO: retro_set_controller_port_device() - * - * The ascending input port indexes provided by the core in the struct - * are generally presented by frontends as ascending User # or Player #, - * such as Player 1, Player 2, Player 3, etc. Which device subclasses are - * supported can vary per input port. - * - * The first inner element of each entry in the retro_controller_info array - * is a retro_controller_description struct that specifies the names and - * codes of all device subclasses that are available for the corresponding - * User or Player, beginning with the generic Libretro device that the - * subclasses are derived from. The second inner element of each entry is the - * total number of subclasses that are listed in the retro_controller_description. - * - * NOTE: Even if special device types are set in the libretro core, - * libretro should only poll input based on the base input device types. - */ + +/** + * 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) - /* const struct retro_memory_map * -- - * This environment call lets a libretro core tell the frontend - * about the memory maps this core emulates. - * This can be used to implement, for example, cheats in a core-agnostic way. - * - * Should only be used by emulators; it doesn't make much sense for - * anything else. - * It is recommended to expose all relevant pointers through - * retro_get_memory_* as well. - * - * Can be called from retro_init and retro_load_game. - */ + +/** + * 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 - /* const struct retro_game_geometry * -- - * This environment call is similar to SET_SYSTEM_AV_INFO for changing - * video parameters, but provides a guarantee that drivers will not be - * reinitialized. - * This can only be called from within retro_run(). - * - * The purpose of this call is to allow a core to alter nominal - * width/heights as well as aspect ratios on-the-fly, which can be - * useful for some emulators to change in run-time. - * - * max_width/max_height arguments are ignored and cannot be changed - * with this call as this could potentially require a reinitialization or a - * non-constant time operation. - * If max_width/max_height are to be changed, SET_SYSTEM_AV_INFO is required. - * - * A frontend must guarantee that this environment call completes in - * constant time. - */ + +/** + * 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 - /* const char ** - * Returns the specified username of the frontend, if specified by the user. - * This username can be used as a nickname for a core that has online facilities - * or any other mode where personalization of the user is desirable. - * The returned value can be NULL. - * If this environ callback is used by a core that requires a valid username, - * a default username should be specified by the core. - */ + +/** + * 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 - /* unsigned * -- - * Returns the specified language of the frontend, if specified by the user. - * It can be used by the core for localization purposes. - */ + +/** + * 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) - /* struct retro_framebuffer * -- - * Returns a preallocated framebuffer which the core can use for rendering - * the frame into when not using SET_HW_RENDER. - * The framebuffer returned from this call must not be used - * after the current call to retro_run() returns. - * - * The goal of this call is to allow zero-copy behavior where a core - * can render directly into video memory, avoiding extra bandwidth cost by copying - * memory from core to video memory. - * - * If this call succeeds and the core renders into it, - * the framebuffer pointer and pitch can be passed to retro_video_refresh_t. - * If the buffer from GET_CURRENT_SOFTWARE_FRAMEBUFFER is to be used, - * the core must pass the exact - * same pointer as returned by GET_CURRENT_SOFTWARE_FRAMEBUFFER; - * i.e. passing a pointer which is offset from the - * buffer is undefined. The width, height and pitch parameters - * must also match exactly to the values obtained from GET_CURRENT_SOFTWARE_FRAMEBUFFER. - * - * It is possible for a frontend to return a different pixel format - * than the one used in SET_PIXEL_FORMAT. This can happen if the frontend - * needs to perform conversion. - * - * It is still valid for a core to render to a different buffer - * even if GET_CURRENT_SOFTWARE_FRAMEBUFFER succeeds. - * - * A frontend must make sure that the pointer obtained from this function is - * writeable (and readable). - */ + +/** + * 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) - /* const struct retro_hw_render_interface ** -- - * Returns an API specific rendering interface for accessing API specific data. - * Not all HW rendering APIs support or need this. - * The contents of the returned pointer is specific to the rendering API - * being used. See the various headers like libretro_vulkan.h, etc. - * - * GET_HW_RENDER_INTERFACE cannot be called before context_reset has been called. - * Similarly, after context_destroyed callback returns, - * the contents of the HW_RENDER_INTERFACE are invalidated. - */ + +/** + * 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) - /* const bool * -- - * If true, the libretro implementation supports achievements - * either via memory descriptors set with RETRO_ENVIRONMENT_SET_MEMORY_MAPS - * or via retro_get_memory_data/retro_get_memory_size. - * - * This must be called before the first call to retro_run. - */ + +/** + * 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) - /* const struct retro_hw_render_context_negotiation_interface * -- - * Sets an interface which lets the libretro core negotiate with frontend how a context is created. - * The semantics of this interface depends on which API is used in SET_HW_RENDER earlier. - * This interface will be used when the frontend is trying to create a HW rendering context, - * so it will be used after SET_HW_RENDER, but before the context_reset callback. - */ + +/** + * 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 - /* uint64_t * -- - * Sets quirk flags associated with serialization. The frontend will zero any flags it doesn't - * recognize or support. Should be set in either retro_init or retro_load_game, but not both. - */ + +/** + * 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) - /* N/A (null) * -- - * The frontend will try to use a 'shared' hardware context (mostly applicable - * to OpenGL) when a hardware context is being set up. - * - * Returns true if the frontend supports shared hardware contexts and false - * if the frontend does not support shared hardware contexts. - * - * This will do nothing on its own until SET_HW_RENDER env callbacks are - * being used. - */ + +/** + * 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) - /* struct retro_vfs_interface_info * -- - * Gets access to the VFS interface. - * VFS presence needs to be queried prior to load_game or any - * get_system/save/other_directory being called to let front end know - * core supports VFS before it starts handing out paths. - * It is recomended to do so in retro_set_environment - */ + +/** + * 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) - /* struct retro_led_interface * -- - * Gets an interface which is used by a libretro core to set - * state of LEDs. - */ + +/** + * 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) - /* int * -- - * Tells the core if the frontend wants audio or video. - * If disabled, the frontend will discard the audio or video, - * so the core may decide to skip generating a frame or generating audio. - * This is mainly used for increasing performance. - * Bit 0 (value 1): Enable Video - * Bit 1 (value 2): Enable Audio - * Bit 2 (value 4): Use Fast Savestates. - * Bit 3 (value 8): Hard Disable Audio - * Other bits are reserved for future use and will default to zero. - * If video is disabled: - * * The frontend wants the core to not generate any video, - * including presenting frames via hardware acceleration. - * * The frontend's video frame callback will do nothing. - * * 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. - * If audio is disabled: - * * The frontend wants the core to not generate any audio. - * * The frontend's audio callbacks will do nothing. - * * 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. - * Fast Savestates: - * * Guaranteed to be created by the same binary that will load them. - * * Will not be written to or read from the disk. - * * Suggest that the core assumes loading state will succeed. - * * Suggest that the core updates its memory buffers in-place if possible. - * * Suggest that the core skips clearing memory. - * * Suggest that the core skips resetting the system. - * * Suggest that the core may skip validation steps. - * Hard Disable Audio: - * * Used for a secondary core when running ahead. - * * Indicates that the frontend will never need audio from the core. - * * Suggests that the core may stop synthesizing audio, but this should not - * compromise 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 when using Hard Disable Audio. - */ + +/** + * 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) - /* struct retro_midi_interface ** -- - * Returns a MIDI interface that can be used for raw data I/O. - */ +/** + * 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) - /* bool * -- - * Boolean value that indicates whether or not the frontend is in - * fastforwarding mode. - */ +/** + * 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) - /* float * -- - * Float value that lets us know what target refresh rate - * is curently in use by the frontend. - * - * The core can use the returned value to set an ideal - * refresh rate/framerate. - */ +/** + * 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) - /* bool * -- - * Boolean value that indicates whether or not the frontend supports - * input bitmasks being returned by retro_input_state_t. The advantage - * of this is that retro_input_state_t has to be only called once to - * grab all button states instead of multiple times. - * - * If it returns true, you can pass RETRO_DEVICE_ID_JOYPAD_MASK as 'id' - * to retro_input_state_t (make sure 'device' is set to RETRO_DEVICE_JOYPAD). - * It will return a bitmask of all the digital buttons. - */ +/** + * 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 - /* unsigned * -- - * Unsigned value is the API version number of the core options - * interface supported by the frontend. If callback return false, - * API version is assumed to be 0. - * - * In legacy code, core options are set by passing an array of - * retro_variable structs to RETRO_ENVIRONMENT_SET_VARIABLES. - * This may be still be done regardless of the core options - * interface version. - * - * If version is >= 1 however, core options may instead be set by - * passing an array of retro_core_option_definition structs to - * RETRO_ENVIRONMENT_SET_CORE_OPTIONS, or a 2D array of - * retro_core_option_definition structs to RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL. - * This allows the core to additionally set option sublabel information - * and/or provide localisation support. - * - * If version is >= 2, core options may instead be set by passing - * a retro_core_options_v2 struct to RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2, - * or an array of retro_core_options_v2 structs to - * RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL. This allows the core - * to additionally set optional core option category information - * for frontends with core option category support. - */ +/** + * @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 - /* const struct retro_core_option_definition ** -- - * Allows an implementation to signal the environment - * which variables it might want to check for later using - * GET_VARIABLE. - * This allows the frontend to present these variables to - * a user dynamically. - * This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION - * returns an API version of >= 1. - * This should be called instead of RETRO_ENVIRONMENT_SET_VARIABLES. - * This should be called the first time as early as - * possible (ideally in retro_set_environment). - * Afterwards it may be called again for the core to communicate - * updated options to the frontend, but the number of core - * options must not change from the number in the initial call. - * - * 'data' points to an array of retro_core_option_definition structs - * terminated by a { NULL, NULL, NULL, {{0}}, NULL } element. - * retro_core_option_definition::key should be namespaced to not collide - * with other implementations' keys. e.g. A core called - * 'foo' should use keys named as 'foo_option'. - * retro_core_option_definition::desc should contain a human readable - * description of the key. - * retro_core_option_definition::info should contain any additional human - * readable information text that a typical user may need to - * understand the functionality of the option. - * retro_core_option_definition::values is an array of retro_core_option_value - * structs terminated by a { NULL, NULL } element. - * > retro_core_option_definition::values[index].value is an expected option - * value. - * > retro_core_option_definition::values[index].label is a human readable - * label used when displaying the value on screen. If NULL, - * the value itself is used. - * retro_core_option_definition::default_value is the default core option - * setting. It must match one of the expected option values in the - * retro_core_option_definition::values array. If it does not, or the - * default value is NULL, the first entry in the - * retro_core_option_definition::values array is treated as the default. - * - * The number of possible option values should be very limited, - * and must be less than RETRO_NUM_CORE_OPTION_VALUES_MAX. - * i.e. it should be feasible to cycle through options - * without a keyboard. - * - * Example entry: - * { - * "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" - * } - * - * Only strings are operated on. The possible values will - * generally be displayed and stored as-is by the frontend. - */ +/** + * 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 - /* const struct retro_core_options_intl * -- - * Allows an implementation to signal the environment - * which variables it might want to check for later using - * GET_VARIABLE. - * This allows the frontend to present these variables to - * a user dynamically. - * This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION - * returns an API version of >= 1. - * This should be called instead of RETRO_ENVIRONMENT_SET_VARIABLES. - * This should be called instead of RETRO_ENVIRONMENT_SET_CORE_OPTIONS. - * This should be called the first time as early as - * possible (ideally in retro_set_environment). - * Afterwards it may be called again for the core to communicate - * updated options to the frontend, but the number of core - * options must not change from the number in the initial call. - * - * This is fundamentally the same as RETRO_ENVIRONMENT_SET_CORE_OPTIONS, - * with the addition of localisation support. The description of the - * RETRO_ENVIRONMENT_SET_CORE_OPTIONS callback should be consulted - * for further details. - * - * 'data' points to a retro_core_options_intl struct. - * - * retro_core_options_intl::us is a pointer to an array of - * retro_core_option_definition structs defining the US English - * core options implementation. It must point to a valid array. - * - * retro_core_options_intl::local is a pointer to an array of - * retro_core_option_definition structs defining core options for - * the current frontend language. It may be NULL (in which case - * retro_core_options_intl::us is used by the frontend). Any items - * missing from this array will be read from retro_core_options_intl::us - * instead. - * - * NOTE: Default core option values are always taken from the - * retro_core_options_intl::us array. Any default values in - * retro_core_options_intl::local array will be ignored. - */ +/** + * 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 - /* struct retro_core_option_display * -- - * - * Allows an implementation to signal the environment to show - * or hide a variable when displaying core options. This is - * considered a *suggestion*. The frontend is free to ignore - * this callback, and its implementation not considered mandatory. - * - * 'data' points to a retro_core_option_display struct - * - * retro_core_option_display::key is a variable identifier - * which has already been set by SET_VARIABLES/SET_CORE_OPTIONS. - * - * retro_core_option_display::visible is a boolean, specifying - * whether variable should be displayed - * - * Note that all core option variables will be set visible by - * default when calling SET_VARIABLES/SET_CORE_OPTIONS. - */ +/** + * 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 - /* unsigned * -- - * - * Allows an implementation to ask frontend preferred hardware - * context to use. Core should use this information to deal - * with what specific context to request with SET_HW_RENDER. - * - * 'data' points to an unsigned variable - */ +/** + * 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 - /* unsigned * -- - * Unsigned value is the API version number of the disk control - * interface supported by the frontend. If callback return false, - * API version is assumed to be 0. - * - * In legacy code, the disk control interface is defined by passing - * a struct of type retro_disk_control_callback to - * RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE. - * This may be still be done regardless of the disk control - * interface version. - * - * If version is >= 1 however, the disk control interface may - * instead be defined by passing a struct of type - * retro_disk_control_ext_callback to - * RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE. - * This allows the core to provide additional information about - * disk images to the frontend and/or enables extra - * disk control functionality by the frontend. - */ +/** + * @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 - /* const struct retro_disk_control_ext_callback * -- - * Sets an interface which frontend can use to eject and insert - * disk images, and also obtain information about individual - * disk image files registered by the core. - * This is used for games which consist of multiple images and - * must be manually swapped out by the user (e.g. PSX, floppy disk - * based systems). - */ +/** + * 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 - /* unsigned * -- - * Unsigned value is the API version number of the message - * interface supported by the frontend. If callback returns - * false, API version is assumed to be 0. - * - * In legacy code, messages may be displayed in an - * implementation-specific manner by passing a struct - * of type retro_message to RETRO_ENVIRONMENT_SET_MESSAGE. - * This may be still be done regardless of the message - * interface version. - * - * If version is >= 1 however, messages may instead be - * displayed by passing a struct of type retro_message_ext - * to RETRO_ENVIRONMENT_SET_MESSAGE_EXT. This allows the - * core to specify message logging level, priority and - * destination (OSD, logging interface or both). - */ +/** + * 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 - /* const struct retro_message_ext * -- - * Sets a message to be displayed in an implementation-specific - * manner for a certain amount of 'frames'. Additionally allows - * the core to specify message logging level, priority and - * destination (OSD, logging interface or both). - * Should not be used for trivial messages, which should simply be - * logged via RETRO_ENVIRONMENT_GET_LOG_INTERFACE (or as a - * fallback, stderr). - */ +/** + * 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 - /* unsigned * -- - * Unsigned value is the number of active input devices - * provided by the frontend. This may change between - * frames, but will remain constant for the duration - * of each frame. - * If callback returns true, a core need not poll any - * input device with an index greater than or equal to - * the number of active devices. - * If callback returns false, the number of active input - * devices is unknown. In this case, all input devices - * should be considered active. - */ +/** + * 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 - /* const struct retro_audio_buffer_status_callback * -- - * Lets the core know the occupancy level of the frontend - * audio buffer. Can be used by a core to attempt frame - * skipping in order to avoid buffer under-runs. - * A core may pass NULL to disable buffer status reporting - * in the frontend. - */ +/** + * 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 - /* const unsigned * -- - * Sets minimum frontend audio latency in milliseconds. - * Resultant audio latency may be larger than set value, - * or smaller if a hardware limit is encountered. A frontend - * is expected to honour requests up to 512 ms. - * - * - If value is less than current frontend - * audio latency, callback has no effect - * - If value is zero, default frontend audio - * latency is set - * - * May be used by a core to increase audio latency and - * therefore decrease the probability of buffer under-runs - * (crackling) when performing 'intensive' operations. - * A core utilising RETRO_ENVIRONMENT_SET_AUDIO_BUFFER_STATUS_CALLBACK - * to implement audio-buffer-based frame skipping may achieve - * optimal results by setting the audio latency to a 'high' - * (typically 6x or 8x) integer multiple of the expected - * frame time. - * - * WARNING: This can only be called from within retro_run(). - * Calling this can require a full reinitialization of audio - * drivers in the frontend, so it is important to call it very - * sparingly, and usually only with the users explicit consent. - * An eventual driver reinitialize will happen so that audio - * callbacks happening after this call within the same retro_run() - * call will target the newly initialized driver. - */ +/** + * 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 - /* const struct retro_fastforwarding_override * -- - * Used by a libretro core to override the current - * fastforwarding mode of the frontend. - * If NULL is passed to this function, the frontend - * will return true if fastforwarding override - * functionality is supported (no change in - * fastforwarding state will occur in this case). - */ #define RETRO_ENVIRONMENT_SET_CONTENT_INFO_OVERRIDE 65 /* const struct retro_system_content_info_override * -- @@ -1504,251 +2273,136 @@ enum retro_mod * 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 - /* const struct retro_core_options_v2 * -- - * Allows an implementation to signal the environment - * which variables it might want to check for later using - * GET_VARIABLE. - * This allows the frontend to present these variables to - * a user dynamically. - * This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION - * returns an API version of >= 2. - * This should be called instead of RETRO_ENVIRONMENT_SET_VARIABLES. - * This should be called instead of RETRO_ENVIRONMENT_SET_CORE_OPTIONS. - * This should be called the first time as early as - * possible (ideally in retro_set_environment). - * Afterwards it may be called again for the core to communicate - * updated options to the frontend, but the number of core - * options must not change from the number in the initial call. - * If RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION returns an API - * version of >= 2, this callback is guaranteed to succeed - * (i.e. callback return value does not indicate success) - * If callback returns true, frontend has core option category - * support. - * If callback returns false, frontend does not have core option - * category support. - * - * 'data' points to a retro_core_options_v2 struct, containing - * of two pointers: - * - retro_core_options_v2::categories is an array of - * retro_core_option_v2_category structs terminated by a - * { NULL, NULL, NULL } element. If retro_core_options_v2::categories - * is NULL, all core options will have no category and will be shown - * at the top level of the frontend core option interface. If frontend - * does not have core option category support, categories array will - * be ignored. - * - retro_core_options_v2::definitions is an array of - * retro_core_option_v2_definition structs terminated by a - * { NULL, NULL, NULL, NULL, NULL, NULL, {{0}}, NULL } - * element. - * - * >> retro_core_option_v2_category notes: - * - * - retro_core_option_v2_category::key should contain string - * that uniquely identifies the core option category. Valid - * key characters are [a-z, A-Z, 0-9, _, -] - * Namespace collisions with other implementations' category - * keys are permitted. - * - retro_core_option_v2_category::desc should contain a human - * readable description of the category key. - * - retro_core_option_v2_category::info should contain any - * additional human readable information text that a typical - * user may need to understand the nature of the core option - * category. - * - * Example entry: - * { - * "advanced_settings", - * "Advanced", - * "Options affecting low-level emulation performance and accuracy." - * } - * - * >> retro_core_option_v2_definition notes: - * - * - retro_core_option_v2_definition::key should be namespaced to not - * collide with other implementations' keys. e.g. A core called - * 'foo' should use keys named as 'foo_option'. Valid key characters - * are [a-z, A-Z, 0-9, _, -]. - * - retro_core_option_v2_definition::desc should contain a human readable - * description of the key. Will be used when the frontend does not - * have core option category support. Examples: "Aspect Ratio" or - * "Video > Aspect Ratio". - * - retro_core_option_v2_definition::desc_categorized should contain a - * human readable description of the key, which will be used when - * frontend has core option category support. Example: "Aspect Ratio", - * where associated retro_core_option_v2_category::desc is "Video". - * If empty or NULL, the string specified by - * retro_core_option_v2_definition::desc will be used instead. - * retro_core_option_v2_definition::desc_categorized will be ignored - * if retro_core_option_v2_definition::category_key is empty or NULL. - * - retro_core_option_v2_definition::info should contain any additional - * human readable information text that a typical user may need to - * understand the functionality of the option. - * - retro_core_option_v2_definition::info_categorized should contain - * any additional human readable information text that a typical user - * may need to understand the functionality of the option, and will be - * used when frontend has core option category support. This is provided - * to accommodate the case where info text references an option by - * name/desc, and the desc/desc_categorized text for that option differ. - * If empty or NULL, the string specified by - * retro_core_option_v2_definition::info will be used instead. - * retro_core_option_v2_definition::info_categorized will be ignored - * if retro_core_option_v2_definition::category_key is empty or NULL. - * - retro_core_option_v2_definition::category_key should contain a - * category identifier (e.g. "video" or "audio") that will be - * assigned to the core option if frontend has core option category - * support. A categorized option will be shown in a subsection/ - * submenu of the frontend core option interface. If key is empty - * or NULL, or if key does not match one of the - * retro_core_option_v2_category::key values in the associated - * retro_core_option_v2_category array, option will have no category - * and will be shown at the top level of the frontend core option - * interface. - * - retro_core_option_v2_definition::values is an array of - * retro_core_option_value structs terminated by a { NULL, NULL } - * element. - * --> retro_core_option_v2_definition::values[index].value is an - * expected option value. - * --> retro_core_option_v2_definition::values[index].label is a - * human readable label used when displaying the value on screen. - * If NULL, the value itself is used. - * - retro_core_option_v2_definition::default_value is the default - * core option setting. It must match one of the expected option - * values in the retro_core_option_v2_definition::values array. If - * it does not, or the default value is NULL, the first entry in the - * retro_core_option_v2_definition::values array is treated as the - * default. - * - * The number of possible option values should be very limited, - * and must be less than RETRO_NUM_CORE_OPTION_VALUES_MAX. - * i.e. it should be feasible to cycle through options - * without a keyboard. - * - * Example entries: - * - * - Uncategorized: - * - * { - * "foo_option", - * "Speed hack coprocessor X", - * NULL, - * "Provides increased performance at the expense of reduced accuracy.", - * NULL, - * NULL, - * { - * { "false", NULL }, - * { "true", NULL }, - * { "unstable", "Turbo (Unstable)" }, - * { NULL, NULL }, - * }, - * "false" - * } - * - * - Categorized: - * - * { - * "foo_option", - * "Advanced > Speed hack coprocessor X", - * "Speed hack coprocessor X", - * "Setting 'Advanced > Speed hack coprocessor X' to 'true' or 'Turbo' provides increased performance at the expense of reduced accuracy", - * "Setting 'Speed hack coprocessor X' to 'true' or 'Turbo' provides increased performance at the expense of reduced accuracy", - * "advanced_settings", - * { - * { "false", NULL }, - * { "true", NULL }, - * { "unstable", "Turbo (Unstable)" }, - * { NULL, NULL }, - * }, - * "false" - * } - * - * Only strings are operated on. The possible values will - * generally be displayed and stored as-is by the frontend. - */ +/** + * 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 - /* const struct retro_core_options_v2_intl * -- - * Allows an implementation to signal the environment - * which variables it might want to check for later using - * GET_VARIABLE. - * This allows the frontend to present these variables to - * a user dynamically. - * This should only be called if RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION - * returns an API version of >= 2. - * This should be called instead of RETRO_ENVIRONMENT_SET_VARIABLES. - * This should be called instead of RETRO_ENVIRONMENT_SET_CORE_OPTIONS. - * This should be called instead of RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL. - * This should be called instead of RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2. - * This should be called the first time as early as - * possible (ideally in retro_set_environment). - * Afterwards it may be called again for the core to communicate - * updated options to the frontend, but the number of core - * options must not change from the number in the initial call. - * If RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION returns an API - * version of >= 2, this callback is guaranteed to succeed - * (i.e. callback return value does not indicate success) - * If callback returns true, frontend has core option category - * support. - * If callback returns false, frontend does not have core option - * category support. - * - * This is fundamentally the same as RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2, - * with the addition of localisation support. The description of the - * RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 callback should be consulted - * for further details. - * - * 'data' points to a retro_core_options_v2_intl struct. - * - * - retro_core_options_v2_intl::us is a pointer to a - * retro_core_options_v2 struct defining the US English - * core options implementation. It must point to a valid struct. - * - * - retro_core_options_v2_intl::local is a pointer to a - * retro_core_options_v2 struct defining core options for - * the current frontend language. It may be NULL (in which case - * retro_core_options_v2_intl::us is used by the frontend). Any items - * missing from this struct will be read from - * retro_core_options_v2_intl::us instead. - * - * NOTE: Default core option values are always taken from the - * retro_core_options_v2_intl::us struct. Any default values in - * the retro_core_options_v2_intl::local struct will be ignored. - */ +/** + * 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 - /* const struct retro_core_options_update_display_callback * -- - * 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(). - */ +/** + * 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 - /* const struct retro_variable * -- - * Allows an implementation to notify the frontend - * that a core option value has changed. - * - * retro_variable::key and retro_variable::value - * must match strings that have been set previously - * via one of the following: - * - * - RETRO_ENVIRONMENT_SET_VARIABLES - * - RETRO_ENVIRONMENT_SET_CORE_OPTIONS - * - RETRO_ENVIRONMENT_SET_CORE_OPTIONS_INTL - * - RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2 - * - RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2_INTL - * - * After changing a core option value via this - * callback, RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE - * will return true. - * - * If data is NULL, no changes will be registered - * and the callback will return true; an - * implementation may therefore pass NULL in order - * to test whether the callback is supported. - */ #define RETRO_ENVIRONMENT_GET_THROTTLE_STATE (71 | RETRO_ENVIRONMENT_EXPERIMENTAL) /* struct retro_throttle_state * -- @@ -1756,356 +2410,1266 @@ enum retro_mod * the frontend is attempting to call retro_run(). */ -/* VFS functionality */ +/** + * 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 + +/** + * Returns the "file browser" start directory of the frontend. + * + * This directory can serve as a start directory for the core in case it + * provides an internal way of loading content. + * + * @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_FILE_BROWSER_START_DIRECTORY 80 + +/**@}*/ -/* File paths: - * File paths passed as parameters when using this API shall be well formed UNIX-style, - * using "/" (unquoted forward slash) as directory separator regardless of the platform's native separator. - * Paths shall also include at least one forward slash ("game.bin" is an invalid path, use "./game.bin" instead). - * Other than the directory separator, cores shall not make assumptions about path format: - * "C:/path/game.bin", "http://example.com/game.bin", "#game/game.bin", "./game.bin" (without quotes) are all valid paths. +/** + * @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 to front end. - * The frontend is encouraged to make such paths work as well as it can, but is allowed to give up if the core alters paths too much. - * Frontends are encouraged, but not required, to support native file system paths (modulo replacing the directory separator, if applicable). - * Cores are allowed to try using them, but must remain functional if the front rejects such requests. + * 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 support VFS. */ + * 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 - * Introduced in VFS API v1 */ +/** + * Opaque file handle. + * @since VFS API v1 + */ struct retro_vfs_file_handle; -/* Opaque directory handle - * Introduced in VFS API v3 */ +/** + * Opaque directory handle. + * @since VFS API v3 + */ struct retro_vfs_dir_handle; -/* File open flags - * Introduced in VFS API v1 */ -#define RETRO_VFS_FILE_ACCESS_READ (1 << 0) /* Read only mode */ -#define RETRO_VFS_FILE_ACCESS_WRITE (1 << 1) /* Write only mode, discard contents and overwrites existing file unless RETRO_VFS_FILE_ACCESS_UPDATE is also specified */ -#define RETRO_VFS_FILE_ACCESS_READ_WRITE (RETRO_VFS_FILE_ACCESS_READ | RETRO_VFS_FILE_ACCESS_WRITE) /* Read-write mode, discard contents and overwrites existing file unless RETRO_VFS_FILE_ACCESS_UPDATE is also specified*/ +/** @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 */ -/* These are only hints. The frontend may choose to ignore them. Other than RAM/CPU/etc use, - and how they react to unlikely external interference (for example someone else writing to that file, - or the file's server going down), behavior will not change. */ +/** @} */ + +/** @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) -/* Indicate that the file will be accessed many times. The frontend should aggressively cache everything. */ + +/** + * 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) -/* Seek positions */ +/** @} */ + +/** @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 -/* stat() result flags - * Introduced in VFS API v3 */ +/** @} */ + +/** @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) -/* Get path from opaque handle. Returns the exact same path passed to file_open when getting the handle - * Introduced in VFS API v1 */ +/** @} */ + +/** + * 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. If path points to a directory, this will - * fail. Returns the opaque file handle, or NULL for error. - * Introduced in VFS API v1 */ +/** + * 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. Must be called if open_file returns non-NULL. Returns 0 on success, -1 on failure. - * Whether the call succeeds ot not, the handle passed as parameter becomes invalid and should no longer be used. - * Introduced in VFS API v1 */ +/** + * 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, or -1 for error. - * Introduced in VFS API v1 */ +/** + * 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); -/* Truncate file to specified size. Returns 0 on success or -1 on error - * Introduced in VFS API v2 */ +/** + * 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); -/* Get the current read / write position for the file. Returns -1 for error. - * Introduced in VFS API v1 */ +/** + * 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); -/* Set the current read/write position for the file. Returns the new position, -1 for error. - * Introduced in VFS API v1 */ +/** + * 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. Returns the number of bytes read, or -1 for error. - * Introduced in VFS API v1 */ +/** + * 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. Returns the number of bytes written, or -1 for error. - * Introduced in VFS API v1 */ +/** + * 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 file, if using buffered IO. Returns 0 on sucess, or -1 on failure. - * Introduced in VFS API v1 */ +/** + * 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); -/* Delete the specified file. Returns 0 on success, -1 on failure - * Introduced in VFS API v1 */ +/** + * 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. Returns 0 on success, -1 on failure - * Introduced in VFS API v1 */ +/** + * 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); -/* Stat the specified file. Retruns a bitmask of RETRO_VFS_STAT_* flags, none are set if path was not valid. - * Additionally stores file size in given variable, unless NULL is given. - * Introduced in VFS API v3 */ +/** + * 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); -/* Create the specified directory. Returns 0 on success, -1 on unknown failure, -2 if already exists. - * Introduced in VFS API v3 */ +/** + * 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); -/* Open the specified directory for listing. Returns the opaque dir handle, or NULL for error. - * Support for the include_hidden argument may vary depending on the platform. - * Introduced in VFS API v3 */ +/** + * 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); -/* Read the directory entry at the current position, and move the read pointer to the next position. - * Returns true on success, false if already on the last entry. - * Introduced in VFS API v3 */ +/** + * 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); -/* Get the name of the last entry read. Returns a string on success, or NULL for error. - * The returned string pointer is valid until the next call to readdir or closedir. - * Introduced in VFS API v3 */ +/** + * 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); -/* Check if the last entry read was a directory. Returns true if it was, false otherwise (or on error). - * Introduced in VFS API v3 */ +/** + * 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); -/* Close the directory and release its resources. Must be called if opendir returns non-NULL. Returns 0 on success, -1 on failure. - * Whether the call succeeds ot not, the handle passed as parameter becomes invalid and should no longer be used. - * Introduced in VFS API v3 */ +/** + * 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 { - /* Set by core: should this be higher than the version the front end supports, - * front end will return false in the RETRO_ENVIRONMENT_GET_VFS_INTERFACE call - * Introduced in VFS API v1 */ + /** + * 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; - /* Frontend writes interface pointer here. The frontend also sets the actual - * version, must be at least required_interface_version. - * Introduced in VFS API v1 */ + /** + * 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 { - RETRO_HW_RENDER_INTERFACE_VULKAN = 0, - RETRO_HW_RENDER_INTERFACE_D3D9 = 1, - RETRO_HW_RENDER_INTERFACE_D3D10 = 2, - RETRO_HW_RENDER_INTERFACE_D3D11 = 3, - RETRO_HW_RENDER_INTERFACE_D3D12 = 4, + /** + * 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, - RETRO_HW_RENDER_INTERFACE_DUMMY = INT_MAX + + /** @private Defined to ensure sizeof(retro_hw_render_interface_type) == sizeof(int). + * Do not use. */ + RETRO_HW_RENDER_INTERFACE_DUMMY = INT_MAX }; -/* Base struct. All retro_hw_render_interface_* types - * contain at least these fields. */ +/** + * 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 { - retro_set_led_state_t set_led_state; + /** + * 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 }; -/* Retrieves the current state of the MIDI input. - * Returns true if it's enabled, false otherwise. */ +/** @} */ + +/** + * @defgroup GET_MIDI_INTERFACE MIDI Interface + * @{ + */ + +/** @copydoc retro_midi_interface::input_enabled */ typedef bool (RETRO_CALLCONV *retro_midi_input_enabled_t)(void); -/* Retrieves the current state of the MIDI output. - * Returns true if it's enabled, false otherwise */ +/** @copydoc retro_midi_interface::output_enabled */ typedef bool (RETRO_CALLCONV *retro_midi_output_enabled_t)(void); -/* Reads next byte from the input stream. - * Returns true if byte is read, false otherwise. */ +/** @copydoc retro_midi_interface::read */ typedef bool (RETRO_CALLCONV *retro_midi_read_t)(uint8_t *byte); -/* Writes byte to the output stream. - * 'delta_time' is in microseconds and represent time elapsed since previous write. - * Returns true if byte is written, false otherwise. */ +/** @copydoc retro_midi_interface::write */ typedef bool (RETRO_CALLCONV *retro_midi_write_t)(uint8_t byte, uint32_t delta_time); -/* Flushes previously written data. - * Returns true if successful, false otherwise. */ +/** @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; }; -enum retro_hw_render_context_negotiation_interface_type -{ - RETRO_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE_VULKAN = 0, +/** @} */ + +/** @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 struct. All retro_hw_render_context_negotiation_interface_* types - * contain at least these fields. */ +/** + * 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; }; -/* Serialized state is incomplete in some way. Set if serialization is - * usable in typical end-user cases but should not be relied upon to - * implement frame-sensitive frontend features such as netplay or - * rerecording. */ +/** @} */ + +/** @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) -/* The core must spend some time initializing before serialization is - * supported. retro_serialize() will initially fail; retro_unserialize() - * and retro_serialize_size() may or may not work correctly either. */ + +/** + * 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) -/* Serialization size may change within a session. */ + +/** 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. */ + +/** 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. */ + +/** 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. */ + +/** + * 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 */ + +/** + * 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) -#define RETRO_MEMDESC_CONST (1 << 0) /* The frontend will never change this memory area once retro_load_game has returned. */ -#define RETRO_MEMDESC_BIGENDIAN (1 << 1) /* The memory area contains big endian data. Default is little endian. */ -#define RETRO_MEMDESC_SYSTEM_RAM (1 << 2) /* The memory area is system RAM. This is main RAM of the gaming system. */ -#define RETRO_MEMDESC_SAVE_RAM (1 << 3) /* The memory area is save RAM. This RAM is usually found on a game cartridge, backed up by a battery. */ -#define RETRO_MEMDESC_VIDEO_RAM (1 << 4) /* The memory area is video RAM (VRAM) */ -#define RETRO_MEMDESC_ALIGN_2 (1 << 16) /* All memory access in this area is aligned to their own size, or 2, whichever is smaller. */ +/** @} */ + +/** @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) -#define RETRO_MEMDESC_MINSIZE_2 (1 << 24) /* All memory in this region is accessed at least 2 bytes at the time. */ + +/** + * 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 the relevant ROM or RAM chip. - * It's strongly recommended to use 'offset' if possible, rather than - * doing math on the pointer. + /** + * 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. * - * If the same byte is mapped my multiple descriptors, their descriptors - * must have the same pointer. - * If 'start' does not point to the first byte in the pointer, put the - * difference in 'offset' instead. + * May be \c NULL to indicate a lack of accessible memory + * at the emulated address given in \c start. * - * May be NULL if there's nothing usable here (e.g. hardware registers and - * open bus). No flags should be set if the pointer is NULL. - * It's recommended to minimize the number of descriptors if possible, - * but not mandatory. */ + * @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; - /* This is the location in the emulated address space - * where the mapping starts. */ + /** + * 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; - /* Which bits must be same as in 'start' for this mapping to apply. - * The first memory descriptor to claim a certain byte is the one - * that applies. - * A bit which is set in 'start' must also be set in this. - * Can be zero, in which case each byte is assumed mapped exactly once. - * In this case, 'len' must be a power of two. */ + /** + * 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; - /* If this is nonzero, the set bits are assumed not connected to the - * memory chip's address pins. */ + /** + * 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; - /* This one tells the size of the current memory area. - * If, after start+disconnect are applied, the address is higher than - * this, the highest bit of the address is cleared. + /** + * 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 infinite (as limited - * by 'select' and 'disconnect'). */ + * Can be zero, in which case it's assumed to be + * bounded only by \ref select and \ref disconnect. + */ size_t len; - /* To go from emulated address to physical address, the following - * order applies: - * Subtract 'start', pick off 'disconnect', apply 'len', add 'offset'. */ - - /* The address space name must consist of only a-zA-Z0-9_-, - * should be as short as feasible (maximum length is 8 plus the NUL), - * and may not be any other address space plus one or more 0-9A-F - * at the end. - * However, multiple memory descriptors for the same address space is - * allowed, and the address space name can be empty. NULL is treated - * as empty. - * - * Address space names are case sensitive, but avoid lowercase if possible. - * The same pointer may exist in multiple address spaces. - * - * Examples: - * blank+blank - valid (multiple things may be mapped in the same namespace) - * 'Sp'+'Sp' - valid (multiple things may be mapped in the same namespace) - * 'A'+'B' - valid (neither is a prefix of each other) - * 'S'+blank - valid ('S' is not in 0-9A-F) - * 'a'+blank - valid ('a' is not in 0-9A-F) - * 'a'+'A' - valid (neither is a prefix of each other) - * 'AR'+blank - valid ('R' is not in 0-9A-F) - * 'ARB'+blank - valid (the B can't be part of the address either, because - * there is no namespace 'AR') - * blank+'B' - not valid, because it's ambigous which address space B1234 - * would refer to. - * The length can't be used for that purpose; the frontend may want - * to append arbitrary data to an address, without a separator. */ + /** + * 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 @@ -2140,535 +3704,1325 @@ struct retro_memory_descriptor * them up. */ }; -/* The frontend may use the largest value of 'start'+'select' in a - * certain namespace to infer the size of the address space. - * - * If the address space is larger than that, a mapping with .ptr=NULL - * should be at the end of the array, with .select set to all ones for - * as long as the address space is big. - * - * Sample descriptors (minus .ptr, and RETRO_MEMFLAG_ on the flags): - * SNES WRAM: - * .start=0x7E0000, .len=0x20000 - * (Note that this must be mapped before the ROM in most cases; some of the - * ROM mappers - * try to claim $7E0000, or at least $7E8000.) - * SNES SPC700 RAM: - * .addrspace="S", .len=0x10000 - * SNES WRAM mirrors: - * .flags=MIRROR, .start=0x000000, .select=0xC0E000, .len=0x2000 - * .flags=MIRROR, .start=0x800000, .select=0xC0E000, .len=0x2000 - * SNES WRAM mirrors, alternate equivalent descriptor: - * .flags=MIRROR, .select=0x40E000, .disconnect=~0x1FFF - * (Various similar constructions can be created by combining parts of - * the above two.) - * SNES LoROM (512KB, mirrored a couple of times): - * .flags=CONST, .start=0x008000, .select=0x408000, .disconnect=0x8000, .len=512*1024 - * .flags=CONST, .start=0x400000, .select=0x400000, .disconnect=0x8000, .len=512*1024 - * SNES HiROM (4MB): - * .flags=CONST, .start=0x400000, .select=0x400000, .len=4*1024*1024 - * .flags=CONST, .offset=0x8000, .start=0x008000, .select=0x408000, .len=4*1024*1024 - * SNES ExHiROM (8MB): - * .flags=CONST, .offset=0, .start=0xC00000, .select=0xC00000, .len=4*1024*1024 - * .flags=CONST, .offset=4*1024*1024, .start=0x400000, .select=0xC00000, .len=4*1024*1024 - * .flags=CONST, .offset=0x8000, .start=0x808000, .select=0xC08000, .len=4*1024*1024 - * .flags=CONST, .offset=4*1024*1024+0x8000, .start=0x008000, .select=0xC08000, .len=4*1024*1024 - * Clarify the size of the address space: - * .ptr=NULL, .select=0xFFFFFF - * .len can be implied by .select in many of them, but was included for clarity. +/** + * 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 { - /* Human-readable description of the controller. Even if using a generic - * input device type, this can be set to the particular device type the - * core uses. */ + /** + * 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; - /* Device type passed to retro_set_controller_port_device(). If the device - * type is a sub-class of a generic input device type, use the - * RETRO_DEVICE_SUBCLASS macro to create an ID. + /** + * 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. * - * E.g. RETRO_DEVICE_SUBCLASS(RETRO_DEVICE_JOYPAD, 1). */ + * @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 extension associated with a memory type, e.g. "psram". */ + /** + * The file extension the frontend should use + * to save this memory region to disk, e.g. "srm" or "sav". + */ const char *extension; - /* The memory type for retro_get_memory(). This should be at - * least 0x100 to avoid conflict with standardized - * libretro memory types. */ + /** + * 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 { - /* Describes what the content is (SGB BIOS, GB ROM, etc). */ + /** + * Human-readable description of what the content represents, + * e.g. "Game Boy ROM". + */ const char *desc; - /* Same definition as retro_get_system_info(). */ + /** @copydoc retro_system_info::valid_extensions */ const char *valid_extensions; - /* Same definition as retro_get_system_info(). */ + /** @copydoc retro_system_info::need_fullpath */ bool need_fullpath; - /* Same definition as retro_get_system_info(). */ + /** @copydoc retro_system_info::block_extract */ bool block_extract; - /* This is set if the content is required to load a game. - * If this is set to false, a zeroed-out retro_game_info can be passed. */ + /** + * 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; - /* Content can have multiple associated persistent - * memory types (retro_get_memory()). */ + /** + * 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 { - /* Human-readable string of the subsystem type, e.g. "Super GameBoy" */ + /** + * 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 computer friendly short string identifier for the subsystem type. - * This name must be [a-z]. - * E.g. if desc is "Super GameBoy", this can be "sgb". - * This identifier can be used for command-line interfaces, etc. + /** + * 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; - /* Infos for each content file. The first entry is assumed to be the - * "most significant" content for frontend purposes. + /** + * 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 file paths based on the content used - * (e.g. savestates), it should use the path for the first ROM to do so. */ + * + * 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; - /* Number of content files associated with a subsystem. */ + /** The length of the array given in \c roms. */ unsigned num_roms; - /* The type passed to retro_load_game_special(). */ + /** A unique identifier passed to retro_load_game_special(). */ unsigned id; }; -typedef void (RETRO_CALLCONV *retro_proc_address_t)(void); +/** @} */ + +/** @defgroup SET_PROC_ADDRESS_CALLBACK Core Function Pointers + * @{ */ -/* libretro API extension functions: - * (None here so far). +/** + * 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 which are actual - * extensions to the libretro API. * - * Frontends should not use this to obtain symbols to standard - * libretro entry points (static linking or dlsym). + * 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 must be called "retro_foo". + * 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 }; -/* Logging function. Takes log level argument as well. */ +/** + * 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; }; -/* Performance related functions */ +/** @} */ + +/** @defgroup GET_PERF_INTERFACE Performance Interface + * @{ + */ + +/** @defgroup RETRO_SIMD CPU Features + * @{ + */ -/* ID values for 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 current time in microseconds. - * Tries to use the most accurate timer available. +/** + * @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); -/* A simple counter. Usually nanoseconds, but can also be CPU cycles. - * Can be used directly if desired (when creating a more sophisticated - * performance counter system). - * */ +/** + * @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 bit-mask of detected CPU features (RETRO_SIMD_*). */ +/** + * 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 frontend to log and/or display the state of performance counters. - * Performance counters can always be poked into manually as well. +/** + * 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); -/* Register a performance counter. - * ident field must be set with a discrete value and other values in - * retro_perf_counter must be 0. - * Registering can be called multiple times. To avoid calling to - * frontend redundantly, you can check registered field first. */ +/** + * 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 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 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); -/* For convenience it can be useful to wrap register, start and stop in macros. - * E.g.: - * #ifdef LOG_PERFORMANCE +/** + * 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 - * ... Blank macros ... + * // 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 * - * These can then be used mid-functions around code snippets. + * // Defined somewhere else in the core. + * extern struct retro_perf_callback perf_cb; * - * extern struct retro_perf_callback perf_cb; * Somewhere in the core. - * - * void do_some_heavy_work(void) + * void retro_run(void) * { - * RETRO_PERFORMANCE_INIT(cb, work_1; - * RETRO_PERFORMANCE_START(cb, work_1); - * heavy_work_1(); - * RETRO_PERFORMANCE_STOP(cb, work_1); - * - * RETRO_PERFORMANCE_INIT(cb, work_2); - * RETRO_PERFORMANCE_START(cb, work_2); - * heavy_work_2(); - * RETRO_PERFORMANCE_STOP(cb, work_2); + * 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) * { - * perf_cb.perf_log(); * Log all perf counters here for example. + * // 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; }; -/* FIXME: Document the sensor API and work out behavior. - * It will be marked as experimental until then. +/** @} */ + +/** + * @defgroup RETRO_SENSOR Sensor Interface + * @{ */ -enum retro_sensor_action + +/** + * 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 the camera driver. Can only be called in retro_run(). */ +/** + * 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 camera driver. Can only be called in retro_run(). */ +/** + * 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); -/* Callback which signals when the camera driver is initialized - * and/or deinitialized. - * retro_camera_start_t can be called in initialized callback. +/** + * 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); -/* A callback for raw framebuffer data. buffer points to an XRGB8888 buffer. - * Width, height and pitch are similar to retro_video_refresh_t. - * First pixel is top-left origin. +/** + * 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); -/* A callback for when OpenGL textures are used. - * - * texture_id is a texture owned by camera driver. - * Its state or content should be considered immutable, except for things like - * texture filtering and clamping. +/** + * Called by the frontend to report a new camera frame, + * delivered as an OpenGL texture. * - * texture_target is the texture target for the GL texture. - * These can include e.g. GL_TEXTURE_2D, GL_TEXTURE_RECTANGLE, and possibly - * more depending on extensions. + * @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). * - * affine points to a packed 3x3 column-major matrix used to apply an affine - * transform to texture coordinates. (affine_matrix * vec3(coord_x, coord_y, 1.0)) - * After transform, normalized texture coord (0, 0) should be bottom-left - * and (1, 1) should be top-right (or (width, height) for RECTANGLE). - * - * GL-specific typedefs are avoided here to avoid relying on gl.h in - * the API definition. + * @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 { - /* Set by libretro core. - * Example bitmask: caps = (1 << RETRO_CAMERA_BUFFER_OPENGL_TEXTURE) | (1 << RETRO_CAMERA_BUFFER_RAW_FRAMEBUFFER). + /** + * 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; - /* Desired resolution for camera. Is only used as a hint. */ + /** + * 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; - /* Set by frontend. */ + /** + * @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; - /* Set by libretro core if raw framebuffer callbacks will be used. */ + /** + * @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; - /* Set by libretro core if OpenGL texture callbacks will be used. */ + /** + * @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; - /* Set by libretro core. Called after camera driver is initialized and - * ready to be started. - * Can be NULL, in which this callback is not called. + /** + * 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; - /* Set by libretro core. Called right before camera driver is - * deinitialized. - * Can be NULL, in which this callback is not called. + /** + * 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; }; -/* Sets the interval of time and/or distance at which to update/poll - * location-based data. - * - * To ensure compatibility with all location-based implementations, - * values for both interval_ms and interval_distance should be provided. - * - * interval_ms is the interval expressed in milliseconds. - * interval_distance is the distance interval expressed in meters. +/** @} */ + +/** @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); -/* Start location services. The device will start listening for changes to the - * current location at regular intervals (which are defined with - * retro_location_set_interval_t). */ +/** @copydoc retro_location_callback::start */ typedef bool (RETRO_CALLCONV *retro_location_start_t)(void); -/* Stop location services. The device will stop listening for changes - * to the current location. */ +/** @copydoc retro_location_callback::stop */ typedef void (RETRO_CALLCONV *retro_location_stop_t)(void); -/* Get the position of the current location. Will set parameters to - * 0 if no new location update has happened since the last time. */ +/** @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); -/* Callback which signals when the location driver is initialized - * and/or deinitialized. - * retro_location_start_t can be called in initialized callback. - */ +/** 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 }; -/* Sets rumble state for joypad plugged in port 'port'. - * Rumble effects are controlled independently, - * and setting e.g. strong rumble does not override weak rumble. - * Strength has a range of [0, 0xffff]. +/** + * Requests a rumble state change for a controller. + * Set by the frontend. * - * Returns true if rumble state request was honored. - * Calling this before first retro_run() is likely to return false. */ + * @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; }; -/* Notifies libretro that audio data should be written. */ +/** @} */ + +/** + * 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); -/* True: Audio driver in frontend is active, and callback is - * expected to be called regularily. - * False: Audio driver in frontend is paused or inactive. - * Audio callback will not be called until set_state has been - * called with true. - * Initial state is false (inactive). +/** + * 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; }; -/* Notifies a libretro core of time spent since last invocation - * of retro_run() in microseconds. - * - * It will be called right before retro_run() every frame. - * The frontend can tamper with timing to support cases like - * fast-forward, slow-motion and framestepping. - * - * In those scenarios the reference frame time value will be used. */ 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; - /* Represents the time of one frame. It is computed as - * 1000000 / fps, but the implementation will resolve the - * rounding to ensure that framestepping, etc is exact. */ + + /** + * 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; }; -/* Notifies a libretro core of the current occupancy - * level of the frontend audio buffer. - * - * - active: 'true' if audio buffer is currently - * in use. Will be 'false' if audio is - * disabled in the frontend - * - * - occupancy: Given as a value in the range [0,100], - * corresponding to the occupancy percentage - * of the audio buffer - * - * - underrun_likely: 'true' if the frontend expects an - * audio buffer underrun during the - * next frame (indicates that a core - * should attempt frame skipping) +/** @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. * - * It will be called right before 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. * */ @@ -2712,10 +5066,19 @@ enum retro_hw_context_type /* Vulkan, see RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE. */ RETRO_HW_CONTEXT_VULKAN = 6, - /* Direct3D, set version_major to select the type of interface - * returned by RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE */ - RETRO_HW_CONTEXT_DIRECT3D = 7, + /* 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 }; @@ -2811,14 +5174,14 @@ struct retro_hw_render_callback * 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. + * The pressed/keycode state can be independent 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 + * Similarly 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, @@ -2829,274 +5192,753 @@ struct retro_keyboard_callback retro_keyboard_event_t callback; }; -/* Callbacks for RETRO_ENVIRONMENT_SET_DISK_CONTROL_INTERFACE & - * RETRO_ENVIRONMENT_SET_DISK_CONTROL_EXT_INTERFACE. - * Should be set for implementations which can swap out multiple disk - * images in runtime. +/** @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. * - * If the implementation can do this automatically, it should strive to do so. - * However, there are cases where the user must manually do so. + * The steps for swapping disk images are generally as follows: * - * Overview: To swap a disk image, eject the disk image with - * set_eject_state(true). - * Set the disk index with set_image_index(index). Insert the disk again - * with set_eject_state(false). + * \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). + * + * @{ */ -/* If ejected is true, "ejects" the virtual disk tray. - * When ejected, the disk image index can be set. +/** + * 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 current eject state. The initial state is 'not 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 current disk index. First disk is index 0. - * If return value is >= get_num_images(), no disk is currently inserted. +/** + * 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); -/* Sets image index. Can only be called when disk is ejected. - * The implementation supports setting "no disk" by using an - * index >= get_num_images(). +/** + * 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); -/* Gets total number of images which are available to use. */ +/** + * @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 associated with index. +/** + * 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. * - * Replacing a disk image with info = NULL will remove the disk image - * from the internal list. - * As a result, calls to get_image_index() can change. + * 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. * - * E.g. replace_image_index(1, NULL), and previous get_image_index() - * returned 4 before. - * Index 1 will be removed, and the new index is 3. + * @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 valid index (get_num_images()) to the internal disk list. - * This will increment subsequent return values from get_num_images() by 1. +/** + * 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 replace_image_index. */ + * 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 initial image to insert in drive when calling - * core_load_game(). - * Since we cannot pass the initial index when loading - * content (this would require a major API change), this - * is set by the frontend *before* calling the core's - * retro_load_game()/retro_load_game_special() implementation. - * A core should therefore cache the index/path values and handle - * them inside retro_load_game()/retro_load_game_special(). - * - If 'index' is invalid (index >= get_num_images()), the - * core should ignore the set value and instead use 0 - * - 'path' is used purely for error checking - i.e. when - * content is loaded, the core should verify that the - * disk specified by 'index' has the specified file 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 - * 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 set path and content path do not match, the core should - * ignore the set 'index' value and instead use 0 - * Returns 'false' if index or 'path' are invalid, or core - * does not support this functionality +/** + * 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); -/* Fetches the path of the specified disk image file. - * Returns 'false' if index is invalid (index >= get_num_images()) - * or path is otherwise unavailable. +/** + * 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); -/* Fetches a core-provided 'label' for the specified disk - * image file. In the simplest case this may be a file name - * (without extension), but for cores with more complex - * content requirements information may be provided to - * facilitate user disk swapping - for example, a core - * running floppy-disk-based content may uniquely label - * save disks, data disks, level disks, etc. with names - * corresponding to in-game disk change prompts (so the - * frontend can provide better user guidance than a 'dumb' - * disk index value). - * Returns 'false' if index is invalid (index >= get_num_images()) - * or label is otherwise unavailable. +/** + * 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; - /* NOTE: Frontend will only attempt to record/restore - * last used disk index if both set_initial_image() - * and get_image_path() are implemented */ - retro_set_initial_image_t set_initial_image; /* Optional - may be NULL */ + /** @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); - retro_get_image_path_t get_image_path; /* Optional - may be NULL */ - retro_get_image_label_t get_image_label; /* Optional - may be NULL */ +/** + * 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. - * 0 bit must be set to 0. - * This pixel format is default for compatibility concerns only. - * If a 15/16-bit pixel format is desired, consider using RGB565. */ + /** + * 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. - * X bits are ignored. */ + /** + * XRGB8888, native endian. + * The most significant byte (the X) is ignored. + */ RETRO_PIXEL_FORMAT_XRGB8888 = 1, - /* RGB565, native endian. - * This pixel format is the recommended format to use if a 15/16-bit - * format is desired as it is the pixel format that is typically - * available on a wide range of low-power devices. - * - * It is also natively supported in APIs like OpenGL ES. */ + /** + * 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, - /* Ensure sizeof() == sizeof(int). */ + /** 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 { - const char *msg; /* Message to be displayed. */ - unsigned frames; /* Duration in frames of 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 frontend 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, - RETRO_MESSAGE_TARGET_LOG -}; -enum retro_message_type -{ + /** + * 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 { - /* Message string to be displayed/logged */ + /** + * 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; - /* Duration (in ms) of message when targeting the OSD */ + + /** + * The duration that \c msg will be displayed on-screen, in milliseconds. + * + * Ignored for \c RETRO_MESSAGE_TARGET_LOG. + */ unsigned duration; - /* Message priority when targeting the OSD - * > When multiple concurrent messages are sent to - * the frontend and the frontend does not have the - * capacity to display them all, messages with the - * *highest* priority value should be shown - * > There is no upper limit to a message priority - * value (within the bounds of the unsigned data type) - * > In the reference frontend (RetroArch), the same - * priority values are used for frontend-generated - * notifications, which are typically assigned values - * between 0 and 3 depending upon importance */ + + /** + * 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; - /* Message logging level (info, warn, error, etc.) */ + + /** + * 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; - /* Message destination: OSD, logging interface or both */ + + /** + * The intended destination of this message. + * + * @see retro_message_target + */ enum retro_message_target target; - /* Message 'type' when targeting the OSD - * > RETRO_MESSAGE_TYPE_NOTIFICATION: Specifies that a - * message should be handled in identical fashion to - * a standard frontend-generated notification - * > RETRO_MESSAGE_TYPE_NOTIFICATION_ALT: Specifies that - * message is a notification that requires user attention - * or action, but that it should be displayed in a manner - * that differs from standard frontend-generated notifications. - * This would typically correspond to messages that should be - * displayed immediately (independently from any internal - * frontend message queue), and/or which should be visually - * distinguishable from frontend-generated notifications. - * For example, a core may wish to inform the user of - * information related to a disk-change event. It is - * expected that the frontend itself may provide a - * notification in this case; if the core sends a - * message of type RETRO_MESSAGE_TYPE_NOTIFICATION, an - * uncomfortable 'double-notification' may occur. A message - * of RETRO_MESSAGE_TYPE_NOTIFICATION_ALT should therefore - * be presented such that visual conflict with regular - * notifications does not occur - * > RETRO_MESSAGE_TYPE_STATUS: Indicates that message - * is not a standard notification. This typically - * corresponds to 'status' indicators, such as a core's - * internal FPS, which are intended to be displayed - * either permanently while a core is running, or in - * a manner that does not suggest user attention or action - * is required. 'Status' type messages should therefore be - * displayed in a different on-screen location and in a manner - * easily distinguishable from both standard frontend-generated - * notifications and messages of type RETRO_MESSAGE_TYPE_NOTIFICATION_ALT - * > RETRO_MESSAGE_TYPE_PROGRESS: Indicates that message reports - * the progress of an internal core task. For example, in cases - * where a core itself handles the loading of content from a file, - * this may correspond to the percentage of the file that has been - * read. Alternatively, an audio/video playback core may use a - * message of type RETRO_MESSAGE_TYPE_PROGRESS to display the current - * playback position as a percentage of the runtime. 'Progress' type - * messages should therefore be displayed as a literal progress bar, - * where: - * - 'retro_message_ext.msg' is the progress bar title/label - * - 'retro_message_ext.progress' determines the length of - * the progress bar - * NOTE: Message type is a *hint*, and may be ignored - * by the frontend. If a frontend lacks support for - * displaying messages via alternate means than standard - * frontend-generated notifications, it will treat *all* - * messages as having the type RETRO_MESSAGE_TYPE_NOTIFICATION */ + + /** + * The intended semantics of this message. + * + * Ignored for \c RETRO_MESSAGE_TARGET_LOG. + * + * @see retro_message_type + */ enum retro_message_type type; - /* Task progress when targeting the OSD and message is - * of type RETRO_MESSAGE_TYPE_PROGRESS - * > -1: Unmetered/indeterminate - * > 0-100: Current progress percentage - * NOTE: Since message type is a hint, a frontend may ignore - * progress values. Where relevant, a core should therefore - * include progress percentage within the message string, + + /** + * The progress of an asynchronous task. + * + * A value between 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 */ + * 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. */ @@ -3114,21 +5956,32 @@ struct retro_input_descriptor 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 { - /* All pointers are owned by libretro implementation, and pointers must - * remain valid until it is unloaded. */ + /** + * Descriptive name of the library. + * + * @note Should not contain any version numbers, etc. + */ + const char *library_name; - const char *library_name; /* Descriptive name of library. Should not - * contain any version numbers, etc. */ - const char *library_version; /* Descriptive version of core. */ + /** + * Descriptive version of the core. + */ + const char *library_version; - const char *valid_extensions; /* A string listing probably content - * extensions the core will be able to - * load, separated with pipe. - * I.e. "bin|rom|iso". - * Typically used for a GUI to filter - * out extensions. */ + /** + * 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 @@ -3366,101 +6219,273 @@ struct retro_game_info_ext 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 { - unsigned base_width; /* Nominal video width of game. */ - unsigned base_height; /* Nominal video height of game. */ - unsigned max_width; /* Maximum possible width of game. */ + /** + * 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. */ - float aspect_ratio; /* Nominal aspect ratio of game. If - * aspect_ratio is <= 0.0, an aspect ratio - * of base_width / base_height is assumed. - * A frontend could override this setting, - * if desired. */ + /** + * 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 { - double fps; /* FPS of video content. */ - double sample_rate; /* Sampling rate of audio. */ + /** 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 { - /* Variable to query in RETRO_ENVIRONMENT_GET_VARIABLE. - * If NULL, obtains the complete environment string if more - * complex parsing is necessary. - * The environment string is formatted as key-value pairs - * delimited by semicolons as so: - * "key1=value1;key2=value2;..." + /** + * 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. If key does not exist, it is set to NULL. */ + /** + * 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 { - /* Variable to configure in RETRO_ENVIRONMENT_SET_CORE_OPTIONS_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; - /* Specifies whether variable should be displayed - * when presenting core options to the user */ + /** + * 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; }; -/* Maximum number of values permitted for a core option - * > Note: We have to set a maximum value due the limitations - * of the C language - i.e. it is not possible to create an - * array of structs each containing a variable sized array, - * so the retro_core_option_definition values array must - * have a fixed size. The size limit of 128 is a balancing - * act - it needs to be large enough to support all 'sane' - * core options, but setting it too large may impact low memory - * platforms. In practise, if a core option has more than - * 128 values then the implementation is likely flawed. - * To quote the above API reference: - * "The number of possible options should be very limited - * i.e. it should be feasible to cycle through options - * without a keyboard." +/** + * 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 { - /* Expected 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 value label. If NULL, value itself - * will be displayed by the frontend */ + /** + * 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 { - /* Variable to query in RETRO_ENVIRONMENT_GET_VARIABLE. */ + /** @copydoc retro_core_option_v2_definition::key */ const char *key; - /* Human-readable core option description (used as menu label) */ + /** @copydoc retro_core_option_v2_definition::desc */ const char *desc; - /* Human-readable core option information (used as menu sublabel) */ + /** @copydoc retro_core_option_v2_definition::info */ const char *info; - /* Array of retro_core_option_value structs, terminated by NULL */ + /** @copydoc retro_core_option_v2_definition::values */ struct retro_core_option_value values[RETRO_NUM_CORE_OPTION_VALUES_MAX]; - /* Default core option value. Must match one of the values - * in the retro_core_option_value array, otherwise will be - * ignored */ + /** @copydoc retro_core_option_v2_definition::default_value */ const char *default_value; }; @@ -3468,156 +6493,325 @@ struct retro_core_option_definition #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 { - /* Pointer to an array of retro_core_option_definition structs - * - US English implementation - * - Must point to a valid array */ + /** @copydoc retro_core_options_v2_intl::us */ struct retro_core_option_definition *us; - /* Pointer to an array of retro_core_option_definition structs - * - Implementation for current frontend language - * - May be NULL */ + /** @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 { - /* Variable uniquely identifying the - * option category. Valid key characters - * are [a-z, A-Z, 0-9, _, -] */ + /** + * 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; - /* Human-readable category description - * > Used as category menu label when - * frontend has core option category - * support */ + /** + * 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; - /* Human-readable category information - * > Used as category menu sublabel when - * frontend has core option category - * support - * > Optional (may be NULL or an empty - * string) */ + /** + * 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 { - /* Variable to query in RETRO_ENVIRONMENT_GET_VARIABLE. - * Valid key characters are [a-z, A-Z, 0-9, _, -] */ + /** + * 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; - /* Human-readable core option description - * > Used as menu label when frontend does - * not have core option category support - * e.g. "Video > Aspect Ratio" */ + /** + * 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; - /* Human-readable core option description - * > Used as menu label when frontend has - * core option category support - * e.g. "Aspect Ratio", where associated - * retro_core_option_v2_category::desc - * is "Video" - * > If empty or NULL, the string specified by - * desc will be used as the menu label - * > Will be ignored (and may be set to NULL) - * if category_key is empty or NULL */ + /** + * 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; - /* Human-readable core option information - * > Used as menu sublabel */ + /** + * 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; - /* Human-readable core option information - * > Used as menu sublabel when frontend - * has core option category support - * (e.g. may be required when info text - * references an option by name/desc, - * and the desc/desc_categorized text - * for that option differ) - * > If empty or NULL, the string specified by - * info will be used as the menu sublabel - * > Will be ignored (and may be set to NULL) - * if category_key is empty or NULL */ + /** + * @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; - /* Variable specifying category (e.g. "video", - * "audio") that will be assigned to the option - * if frontend has core option category support. - * > Categorized options will be displayed in a - * subsection/submenu of the frontend core - * option interface - * > Specified string must match one of the - * retro_core_option_v2_category::key values - * in the associated retro_core_option_v2_category - * array; If no match is not found, specified - * string will be considered as NULL - * > If specified string is empty or NULL, option will - * have no category and will be shown at the top - * level of the frontend core option interface */ + /** + * 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; - /* Array of retro_core_option_value structs, terminated by NULL */ + /** + * 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]; - /* Default core option value. Must match one of the values - * in the retro_core_option_value array, otherwise will be - * ignored */ + /** + * 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 { - /* Array of retro_core_option_v2_category structs, - * terminated by NULL - * > If NULL, all entries in definitions array - * will have no category and will be shown at - * the top level of the frontend core option - * interface - * > Will be ignored if frontend does not have - * core option category support */ + /** + * 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; - /* Array of retro_core_option_v2_definition structs, - * terminated by NULL */ + /** + * 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 retro_core_options_v2 struct - * > US English implementation - * > Must point to a valid struct */ + /** + * 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 retro_core_options_v2 struct - * - Implementation for current frontend language - * - May be NULL */ + /** + * 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; }; -/* Used by the frontend to monitor changes in core option - * visibility. May be called each time any core option - * value is set via the frontend. - * - On each invocation, the core must update the visibility - * of any dynamically hidden options using the - * RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY environment - * callback. - * - On the first invocation, returns 'true' if the visibility - * of any core option has changed since the last call of - * retro_load_game() or retro_load_game_special(). - * - On each subsequent invocation, returns 'true' if the - * visibility of any core option has changed since the last - * time the function was called. */ +/** + * 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. @@ -3634,260 +6828,997 @@ struct retro_game_info 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) - /* The core will write to the buffer provided by retro_framebuffer::data. */ + +/** Indicates that the core will read from the framebuffer returned by the frontend. */ #define RETRO_MEMORY_ACCESS_READ (1 << 1) - /* The core will read from retro_framebuffer::data. */ + +/** @} */ + +/** @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) - /* The memory in data is cached. - * If not cached, random writes and/or reading from the buffer is expected to be very slow. */ + +/** @} */ + +/** + * 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 { - void *data; /* The framebuffer which the core can render into. - Set by frontend in GET_CURRENT_SOFTWARE_FRAMEBUFFER. - The initial contents of data are unspecified. */ - unsigned width; /* The framebuffer width used by the core. Set by core. */ - unsigned height; /* The framebuffer height used by the core. Set by core. */ - size_t pitch; /* The number of bytes between the beginning of a scanline, - and beginning of the next scanline. - Set by frontend in GET_CURRENT_SOFTWARE_FRAMEBUFFER. */ - enum retro_pixel_format format; /* The pixel format the core must use to render into data. - This format could differ from the format used in - SET_PIXEL_FORMAT. - Set by frontend in GET_CURRENT_SOFTWARE_FRAMEBUFFER. */ - - unsigned access_flags; /* How the core will access the memory in the framebuffer. - RETRO_MEMORY_ACCESS_* flags. - Set by core. */ - unsigned memory_flags; /* Flags telling core how the memory has been mapped. - RETRO_MEMORY_TYPE_* flags. - Set by frontend in GET_CURRENT_SOFTWARE_FRAMEBUFFER. */ -}; - -/* Used by a libretro core to override the current - * fastforwarding mode of the frontend */ + /** + * 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 { - /* Specifies the runtime speed multiplier that - * will be applied when 'fastforward' is true. - * For example, a value of 5.0 when running 60 FPS - * content will cap the fast-forward rate at 300 FPS. - * Note that the target multiplier may not be achieved - * if the host hardware has insufficient processing - * power. - * Setting a value of 0.0 (or greater than 0.0 but - * less than 1.0) will result in an uncapped - * fast-forward rate (limited only by hardware - * capacity). - * If the value is negative, it will be ignored - * (i.e. the frontend will use a runtime speed - * multiplier of its own choosing) */ + /** + * 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 true, fastforwarding mode will be enabled. - * If false, fastforwarding mode will be disabled. */ + /** + * 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 true, and if supported by the frontend, an - * on-screen notification will be displayed while - * 'fastforward' is true. - * If false, and if supported by the frontend, any - * on-screen fast-forward notifications will be - * suppressed */ + /** + * 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 true, the core will have sole control over - * when fastforwarding mode is enabled/disabled; - * the frontend will not be able to change the - * state set by 'fastforward' until either - * 'inhibit_toggle' is set to false, or the core - * is unloaded */ + /** + * 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. Rate will be equal to the core's internal FPS. */ +/** @} */ + +/** + * 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. Rate will be 0. */ +/** + * While paused or stepping single frames. + * + * @note Rate will be 0. + */ #define RETRO_THROTTLE_FRAME_STEPPING 1 -/* During fast forwarding. - * Rate will be 0 if not specifically limited to a maximum speed. */ +/** + * 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. Rate will be less than the core's internal FPS. */ +/** + * 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. Rate can vary depending on the rewind - * speed or be 0 if the frontend is not aiming for a specific rate. */ +/** + * 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. Rate is the target refresh rate. */ +/** + * 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. Rate will be 0. - * An example could be if no vsync or audio output is active. */ +/** + * 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. Should be one of the values above. */ + /** + * 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. - * Depending on the mode, it can be 0 if there is no known fixed rate. + /** + * 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. */ + * the frontend is longer than what is available for one frame. + */ float rate; }; -/* Callbacks */ +/** @defgroup GET_MICROPHONE_INTERFACE Microphone Interface + * @{ + */ -/* Environment callback. Gives implementations a way of performing - * uncommon tasks. Extensible. */ -typedef bool (RETRO_CALLCONV *retro_environment_t)(unsigned cmd, void *data); +/** + * 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); -/* Render a frame. Pixel format is 15-bit 0RGB1555 native endian - * unless changed (see RETRO_ENVIRONMENT_SET_PIXEL_FORMAT). +/** + * The current version of the microphone interface. + * Will be incremented whenever \c retro_microphone_interface or \c retro_microphone_params_t + * receive new fields. * - * Width and height specify dimensions of buffer. - * Pitch specifices length in bytes between two lines in buffer. + * 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. * - * For performance reasons, it is highly recommended to have a frame + * @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. - * Format is signed 16-bit native endian. +/** + * 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. +/** + * 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. * - * One frame is defined as a sample of left and right channels, interleaved. - * I.e. int16_t buf[4] = { l, r, l, r }; would be 2 frames. - * Only one of the audio callbacks must ever be used. + * @return The number of frames 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. */ +/** + * Polls input. + * + * @see retro_set_input_poll() + */ typedef void (RETRO_CALLCONV *retro_input_poll_t)(void); -/* Queries for input for player 'port'. device will be masked with - * RETRO_DEVICE_MASK. +/** + * 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. * - * Specialization of devices such as RETRO_DEVICE_JOYPAD_MULTITAP that - * have been set with retro_set_controller_port_device() - * will still use the higher level 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 callbacks. retro_set_environment() is guaranteed to be called - * before retro_init(). +/** + * 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. * - * The rest of the set_* functions are guaranteed to have been called - * before the first call to retro_run() is made. */ -RETRO_API void retro_set_environment(retro_environment_t); -RETRO_API void retro_set_video_refresh(retro_video_refresh_t); -RETRO_API void retro_set_audio_sample(retro_audio_sample_t); -RETRO_API void retro_set_audio_sample_batch(retro_audio_sample_batch_t); -RETRO_API void retro_set_input_poll(retro_input_poll_t); -RETRO_API void retro_set_input_state(retro_input_state_t); + * @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); + +/** + * @} + */ -/* Library global initialization/deinitialization. */ +/** + * 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); -/* Must return RETRO_API_VERSION. Used to validate ABI compatibility - * when the API is revised. */ +/** + * 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. Pointers provided in *info - * must be statically allocated. - * Can be called at any time, even before retro_init(). */ +/** + * 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. - * Can be called only after retro_load_game() has successfully completed. - * NOTE: The implementation of this function might not initialize every - * variable if needed. - * E.g. geom.aspect_ratio might not be initialized if core doesn't - * desire a particular aspect ratio. */ +/** + * 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, RETRO_DEVICE_JOYPAD is assumed to be plugged into all +/** + * Sets device to be used for player 'port'. + * + * By default, \c RETRO_DEVICE_JOYPAD is assumed to be plugged into all * available ports. - * Setting a particular device type is not a guarantee that libretro cores + * + * @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. * - * As part of the core's implementation of retro_set_controller_port_device, - * the core should call RETRO_ENVIRONMENT_SET_INPUT_DESCRIPTORS to notify the + * @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 current game. */ +/** + * 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 retro_run(), input_poll callback must be called at least once. +/** + * 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. * - * If a frame is not rendered for reasons where a game "dropped" a frame, - * this still counts as a frame, and retro_run() should explicitly dupe - * a frame if 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). - * Between calls to retro_load_game() and retro_unload_game(), the +/** + * 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 internal state. If failed, or size is lower than - * retro_serialize_size(), it should return false, true otherwise. */ +/** + * 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. - * Return true to indicate successful loading and false to indicate load failure. +/** + * 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); -/* Loads a "special" kind of game. Should not be used, - * except in extreme cases. */ +/** + * 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. Called before retro_deinit(void). */ +/** + * 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 region of game. */ +/** + * 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); -/* Gets region of memory. */ +/** + * 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 diff --git a/platform/libretro/libretro-common/include/retro_common.h b/platform/libretro/libretro-common/include/retro_common.h index a715a28c4..16ac6357d 100644 --- a/platform/libretro/libretro-common/include/retro_common.h +++ b/platform/libretro/libretro-common/include/retro_common.h @@ -23,12 +23,12 @@ #ifndef _LIBRETRO_COMMON_RETRO_COMMON_H #define _LIBRETRO_COMMON_RETRO_COMMON_H -/* -This file is designed to normalize the libretro-common compiling environment. -It is not to be used in public API headers, as they should be designed as leanly as possible. -Nonetheless.. in the meantime, if you do something like use ssize_t, which is not fully portable, -in a public API, you may need this. -*/ +/*! + * @internal This file is designed to normalize the libretro-common compiling environment. + * It is not to be used in public API headers, as they should be designed as leanly as possible. + * Nonetheless.. in the meantime, if you do something like use ssize_t, which is not fully portable, + * in a public API, you may need this. + */ /* conditional compilation is handled inside here */ #include diff --git a/platform/libretro/libretro-common/include/retro_common_api.h b/platform/libretro/libretro-common/include/retro_common_api.h index 0f68b7d98..9f43113c4 100644 --- a/platform/libretro/libretro-common/include/retro_common_api.h +++ b/platform/libretro/libretro-common/include/retro_common_api.h @@ -101,11 +101,31 @@ typedef int ssize_t; #define STRING_REP_UINT64 "%" PRIu64 #define STRING_REP_USIZE "%" PRIuPTR +/* Wrap a declaration in RETRO_DEPRECATED() to produce a compiler warning when +it's used. This is intended for developer machines, so it won't work on ancient +or obscure compilers */ +#if defined(_MSC_VER) +#if _MSC_VER >= 1400 /* Visual C 2005 or later */ +#define RETRO_DEPRECATED(decl) __declspec(deprecated) decl +#endif +#elif defined(__GNUC__) +#if __GNUC__ >= 3 /* GCC 3 or later */ +#define RETRO_DEPRECATED(decl) decl __attribute__((deprecated)) +#endif +#elif defined(__clang__) +#if __clang_major__ >= 3 /* clang 3 or later */ +#define RETRO_DEPRECATED(decl) decl __attribute__((deprecated)) +#endif +#endif +#ifndef RETRO_DEPRECATED /* Unsupported compilers */ +#define RETRO_DEPRECATED(decl) decl +#endif + /* I would like to see retro_inline.h moved in here; possibly boolean too. rationale: these are used in public APIs, and it is easier to find problems -and write code that works the first time portably when theyre included uniformly +and write code that works the first time portably when they are included uniformly than to do the analysis from scratch each time you think you need it, for each feature. Moreover it helps force you to make hard decisions: if you EVER bring in boolean.h, diff --git a/platform/libretro/libretro-common/include/retro_dirent.h b/platform/libretro/libretro-common/include/retro_dirent.h index 3b041679b..d4af7e27d 100644 --- a/platform/libretro/libretro-common/include/retro_dirent.h +++ b/platform/libretro/libretro-common/include/retro_dirent.h @@ -28,50 +28,142 @@ #include +/** @defgroup dirent Directory Entries + * @{ + */ + RETRO_BEGIN_DECLS +/** + * The minimum VFS version (as defined in \c retro_vfs_interface_info::required_interface_version) + * required by the \c dirent functions. + * If no acceptable VFS interface is provided, + * all dirent functions will fall back to libretro-common's implementations. + * @see retro_vfs_interface_info + */ #define DIRENT_REQUIRED_VFS_VERSION 3 +/** + * Installs a frontend-provided VFS interface for the dirent functions to use + * instead of libretro-common's built-in implementations. + * + * @param vfs_info The VFS interface returned by the frontend. + * The dirent functions will fall back to libretro-common's implementations + * if \c vfs_info::required_interface_version is too low. + * @see retro_vfs_interface_info + * @see RETRO_ENVIRONMENT_GET_VFS_INTERFACE + */ void dirent_vfs_init(const struct retro_vfs_interface_info* vfs_info); +/** + * Opaque handle to a directory entry (aka "dirent"). + * It may name a file, directory, or other filesystem object. + * @see retro_opendir + */ typedef struct RDIR RDIR; /** + * Opens a directory for reading. * - * retro_opendir: - * @name : path to the directory to open. - * - * Opens a directory for reading. Tidy up with retro_closedir. - * - * Returns: RDIR pointer on success, NULL if name is not a - * valid directory, null itself or the empty string. + * @param name Path to a directory to open. + * @return An \c RDIR representing the given directory if successful. + * Returns \c NULL if \c name is \c NULL, the empty string, or does not name a directory. + * @note The returned \c RDIR must be closed with \c retro_closedir. + * @see retro_opendir_include_hidden + * @see retro_closedir */ struct RDIR *retro_opendir(const char *name); +/** + * @copybrief retro_opendir + * + * @param name Path to the directory to open. + * @param include_hidden Whether to include hidden files and directories + * when iterating over this directory with \c retro_readdir. + * Platforms and filesystems have different notions of "hidden" files. + * Setting this to \c false will not prevent this function from opening \c name. + * @return An \c RDIR representing the given directory if successful. + * Returns \c NULL if \c name is \c NULL, the empty string, or does not name a directory. + * @note The returned \c RDIR must be closed with \c retro_closedir. + * @see retro_opendir + * @see retro_closedir + */ struct RDIR *retro_opendir_include_hidden(const char *name, bool include_hidden); +/** + * Reads the next entry in the given directory. + * + * Here's a usage example that prints the names of all files in the current directory: + * @code + * struct RDIR *rdir = retro_opendir("."); + * if (rdir) + * { + * while (retro_readdir(rdir)) + * { + * const char *name = retro_dirent_get_name(rdir); + * printf("%s\n", name); + * } + * retro_closedir(rdir); + * rdir = NULL; + * } + * @endcode + * + * @param rdir The directory to iterate over. + * Behavior is undefined if \c NULL. + * @return \c true if the next entry was read successfully, + * \c false if there are no more entries to read or if there was an error. + * @note This may include "." and ".." on Unix-like platforms. + * @see retro_dirent_get_name + * @see retro_dirent_is_dir + */ int retro_readdir(struct RDIR *rdir); -/* Deprecated, returns false, left for compatibility */ +/** + * @deprecated Left for compatibility. + * @param rdir Ignored. + * @return \c false. + */ bool retro_dirent_error(struct RDIR *rdir); +/** + * Gets the name of the dirent's current file or directory. + * + * @param rdir The dirent to get the name of. + * Behavior is undefined if \c NULL. + * @return The name of the directory entry (file, directory, etc.) that the dirent points to. + * Will return \c NULL if there was an error, + * \c retro_readdir has not been called on \c rdir, + * or if there are no more entries to read. + * @note This returns only a name, not a full path. + * @warning The returned string is managed by the VFS implementation + * and must not be modified or freed by the caller. + * @warning The returned string is only valid until the next call to \c retro_readdir. + * @see retro_readdir + */ const char *retro_dirent_get_name(struct RDIR *rdir); /** + * Checks if the given \c RDIR's current dirent names a directory. * - * retro_dirent_is_dir: - * @rdir : pointer to the directory entry. - * @unused : deprecated, included for compatibility reasons, pass NULL - * - * Is the directory listing entry a directory? - * - * Returns: true if directory listing entry is - * a directory, false if not. + * @param rdir The directory entry to check. + * Behavior is undefined if \c NULL. + * @param unused Ignored for compatibility reasons. Pass \c NULL. + * @return \c true if \c rdir refers to a directory, otherwise \c false. + * @see retro_readdir */ bool retro_dirent_is_dir(struct RDIR *rdir, const char *unused); +/** + * Closes an opened \c RDIR that was returned by \c retro_opendir. + * + * @param rdir The directory entry to close. + * If \c NULL, this function does nothing. + * @see retro_vfs_closedir_t + */ void retro_closedir(struct RDIR *rdir); RETRO_END_DECLS +/** @} */ + #endif diff --git a/platform/libretro/libretro-common/include/retro_endianness.h b/platform/libretro/libretro-common/include/retro_endianness.h index aefffef80..8638b2c39 100644 --- a/platform/libretro/libretro-common/include/retro_endianness.h +++ b/platform/libretro/libretro-common/include/retro_endianness.h @@ -31,12 +31,22 @@ #define SWAP16 _byteswap_ushort #define SWAP32 _byteswap_ulong #else +/** + * Swaps the byte order of a 16-bit unsigned integer. + * @param x The integer to byteswap. + * @return \c with its two bytes swapped. + */ static INLINE uint16_t SWAP16(uint16_t x) { return ((x & 0x00ff) << 8) | ((x & 0xff00) >> 8); } +/** + * Swaps the byte order of a 32-bit unsigned integer. + * @param x The integer to byteswap. + * @return \c with its bytes swapped. + */ static INLINE uint32_t SWAP32(uint32_t x) { return ((x & 0x000000ff) << 24) | @@ -61,6 +71,11 @@ static INLINE uint64_t SWAP64(uint64_t val) | ((val & 0xff00000000000000) >> 56); } #else +/** + * Swaps the byte order of a 64-bit unsigned integer. + * @param x The integer to byteswap. + * @return \c with its bytes swapped. + */ static INLINE uint64_t SWAP64(uint64_t val) { return ((val & 0x00000000000000ffULL) << 56) @@ -74,28 +89,29 @@ static INLINE uint64_t SWAP64(uint64_t val) } #endif - -#if defined (LSB_FIRST) || defined (MSB_FIRST) -# warning Defining MSB_FIRST and LSB_FIRST in compile options is deprecated -# undef LSB_FIRST -# undef MSB_FIRST -#endif - #ifdef _MSC_VER /* MSVC pre-defines macros depending on target arch */ #if defined (_M_IX86) || defined (_M_AMD64) || defined (_M_ARM) || defined (_M_ARM64) +#ifndef LSB_FIRST #define LSB_FIRST 1 +#endif #elif _M_PPC +#ifndef MSB_FIRST #define MSB_FIRST 1 +#endif #else /* MSVC can run on _M_ALPHA and _M_IA64 too, but they're both bi-endian; need to find what mode MSVC runs them at */ #error "unknown platform, can't determine endianness" #endif #else #if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__ +#ifndef MSB_FIRST #define MSB_FIRST 1 +#endif #elif __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ +#ifndef LSB_FIRST #define LSB_FIRST 1 +#endif #else #error "Invalid endianness macros" #endif @@ -123,25 +139,20 @@ static INLINE uint64_t SWAP64(uint64_t val) /** - * is_little_endian: - * - * Checks if the system is little endian or big-endian. + * Checks if the current CPU is little-endian. * - * Returns: greater than 0 if little-endian, - * otherwise big-endian. - **/ + * @return \c true on little-endian CPUs, + * \c false on big-endian CPUs. + */ #define is_little_endian() RETRO_IS_LITTLE_ENDIAN /** - * swap_if_big64: - * @val : unsigned 64-bit value + * Byte-swaps an unsigned 64-bit integer on big-endian CPUs. * - * Byteswap unsigned 64-bit value if system is big-endian. - * - * Returns: Byteswapped value in case system is big-endian, - * otherwise returns same value. - **/ - + * @param val The value to byteswap if necessary. + * @return \c val byteswapped on big-endian CPUs, + * \c val unchanged on little-endian CPUs. + */ #if RETRO_IS_BIG_ENDIAN #define swap_if_big64(val) (SWAP64(val)) #elif RETRO_IS_LITTLE_ENDIAN @@ -149,15 +160,12 @@ static INLINE uint64_t SWAP64(uint64_t val) #endif /** - * swap_if_big32: - * @val : unsigned 32-bit value - * - * Byteswap unsigned 32-bit value if system is big-endian. + * Byte-swaps an unsigned 32-bit integer on big-endian CPUs. * - * Returns: Byteswapped value in case system is big-endian, - * otherwise returns same value. - **/ - + * @param val The value to byteswap if necessary. + * @return \c val byteswapped on big-endian CPUs, + * \c val unchanged on little-endian CPUs. + */ #if RETRO_IS_BIG_ENDIAN #define swap_if_big32(val) (SWAP32(val)) #elif RETRO_IS_LITTLE_ENDIAN @@ -165,15 +173,12 @@ static INLINE uint64_t SWAP64(uint64_t val) #endif /** - * swap_if_little64: - * @val : unsigned 64-bit value + * Byte-swaps an unsigned 64-bit integer on little-endian CPUs. * - * Byteswap unsigned 64-bit value if system is little-endian. - * - * Returns: Byteswapped value in case system is little-endian, - * otherwise returns same value. - **/ - + * @param val The value to byteswap if necessary. + * @return \c val byteswapped on little-endian CPUs, + * \c val unchanged on big-endian CPUs. + */ #if RETRO_IS_BIG_ENDIAN #define swap_if_little64(val) (val) #elif RETRO_IS_LITTLE_ENDIAN @@ -181,15 +186,12 @@ static INLINE uint64_t SWAP64(uint64_t val) #endif /** - * swap_if_little32: - * @val : unsigned 32-bit value - * - * Byteswap unsigned 32-bit value if system is little-endian. + * Byte-swaps an unsigned 32-bit integer on little-endian CPUs. * - * Returns: Byteswapped value in case system is little-endian, - * otherwise returns same value. - **/ - + * @param val The value to byteswap if necessary. + * @return \c val byteswapped on little-endian CPUs, + * \c val unchanged on big-endian CPUs. + */ #if RETRO_IS_BIG_ENDIAN #define swap_if_little32(val) (val) #elif RETRO_IS_LITTLE_ENDIAN @@ -197,15 +199,12 @@ static INLINE uint64_t SWAP64(uint64_t val) #endif /** - * swap_if_big16: - * @val : unsigned 16-bit value + * Byte-swaps an unsigned 16-bit integer on big-endian systems. * - * Byteswap unsigned 16-bit value if system is big-endian. - * - * Returns: Byteswapped value in case system is big-endian, - * otherwise returns same value. - **/ - + * @param val The value to byteswap if necessary. + * @return \c val byteswapped on big-endian systems, + * \c val unchanged on little-endian systems. + */ #if RETRO_IS_BIG_ENDIAN #define swap_if_big16(val) (SWAP16(val)) #elif RETRO_IS_LITTLE_ENDIAN @@ -213,15 +212,12 @@ static INLINE uint64_t SWAP64(uint64_t val) #endif /** - * swap_if_little16: - * @val : unsigned 16-bit value + * Byte-swaps an unsigned 16-bit integer on little-endian systems. * - * Byteswap unsigned 16-bit value if system is little-endian. - * - * Returns: Byteswapped value in case system is little-endian, - * otherwise returns same value. - **/ - + * @param val The value to byteswap if necessary. + * @return \c val byteswapped on little-endian systems, + * \c val unchanged on big-endian systems. + */ #if RETRO_IS_BIG_ENDIAN #define swap_if_little16(val) (val) #elif RETRO_IS_LITTLE_ENDIAN @@ -229,167 +225,143 @@ static INLINE uint64_t SWAP64(uint64_t val) #endif /** - * store32be: - * @addr : pointer to unsigned 32-bit buffer - * @data : unsigned 32-bit value to write + * Stores a 32-bit integer in at the given address, in big-endian order. * - * Write data to address. Endian-safe. Byteswaps the data - * first if necessary before storing it. - **/ + * @param addr The address to store the value at. + * Behavior is undefined if \c NULL or not aligned to a 32-bit boundary. + * @param data The value to store in \c addr. + * Will be byteswapped if on a little-endian CPU. + */ static INLINE void store32be(uint32_t *addr, uint32_t data) { *addr = swap_if_little32(data); } /** - * load32be: - * @addr : pointer to unsigned 32-bit buffer + * Loads a 32-bit integer order from the given address, in big-endian order. * - * Load value from address. Endian-safe. - * - * Returns: value from address, byte-swapped if necessary. - **/ + * @param addr The address to load the value from. + * Behavior is undefined if \c NULL or not aligned to a 32-bit boundary. + * @return The value at \c addr, byteswapped if on a little-endian CPU. + */ static INLINE uint32_t load32be(const uint32_t *addr) { return swap_if_little32(*addr); } /** - * retro_cpu_to_le16: - * @val : unsigned 16-bit value + * Converts the given unsigned 16-bit integer to little-endian order if necessary. * - * Convert unsigned 16-bit value from system to little-endian. - * - * Returns: Little-endian representation of val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a big-endian CPU, + * unchanged otherwise. + */ #define retro_cpu_to_le16(val) swap_if_big16(val) /** - * retro_cpu_to_le32: - * @val : unsigned 32-bit value - * - * Convert unsigned 32-bit value from system to little-endian. + * Converts the given unsigned 32-bit integer to little-endian order if necessary. * - * Returns: Little-endian representation of val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a big-endian CPU, + * unchanged otherwise. + */ #define retro_cpu_to_le32(val) swap_if_big32(val) /** - * retro_cpu_to_le64: - * @val : unsigned 64-bit value + * Converts the given unsigned 64-bit integer to little-endian order if necessary. * - * Convert unsigned 64-bit value from system to little-endian. - * - * Returns: Little-endian representation of val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a big-endian CPU, + * unchanged otherwise. + */ #define retro_cpu_to_le64(val) swap_if_big64(val) /** - * retro_le_to_cpu16: - * @val : unsigned 16-bit value + * Converts the given unsigned 16-bit integer to host-native order if necessary. * - * Convert unsigned 16-bit value from little-endian to native. - * - * Returns: Native representation of little-endian val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a big-endian CPU, + * unchanged otherwise. + */ #define retro_le_to_cpu16(val) swap_if_big16(val) /** - * retro_le_to_cpu32: - * @val : unsigned 32-bit value - * - * Convert unsigned 32-bit value from little-endian to native. + * Converts the given unsigned 32-bit integer to host-native order if necessary. * - * Returns: Native representation of little-endian val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a big-endian CPU, + * unchanged otherwise. + */ #define retro_le_to_cpu32(val) swap_if_big32(val) /** - * retro_le_to_cpu16: - * @val : unsigned 64-bit value - * - * Convert unsigned 64-bit value from little-endian to native. + * Converts the given unsigned 64-bit integer to host-native order if necessary. * - * Returns: Native representation of little-endian val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a big-endian CPU, + * unchanged otherwise. + */ #define retro_le_to_cpu64(val) swap_if_big64(val) /** - * retro_cpu_to_be16: - * @val : unsigned 16-bit value + * Converts the given unsigned 16-bit integer to big-endian order if necessary. * - * Convert unsigned 16-bit value from system to big-endian. - * - * Returns: Big-endian representation of val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a little-endian CPU, + * unchanged otherwise. + */ #define retro_cpu_to_be16(val) swap_if_little16(val) /** - * retro_cpu_to_be32: - * @val : unsigned 32-bit value - * - * Convert unsigned 32-bit value from system to big-endian. + * Converts the given unsigned 32-bit integer to big-endian order if necessary. * - * Returns: Big-endian representation of val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a little-endian CPU, + * unchanged otherwise. + */ #define retro_cpu_to_be32(val) swap_if_little32(val) /** - * retro_cpu_to_be64: - * @val : unsigned 64-bit value - * - * Convert unsigned 64-bit value from system to big-endian. + * Converts the given unsigned 64-bit integer to big-endian order if necessary. * - * Returns: Big-endian representation of val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a little-endian CPU, + * unchanged otherwise. + */ #define retro_cpu_to_be64(val) swap_if_little64(val) /** - * retro_be_to_cpu16: - * @val : unsigned 16-bit value + * Converts the given unsigned 16-bit integer from big-endian to host-native order if necessary. * - * Convert unsigned 16-bit value from big-endian to native. - * - * Returns: Native representation of big-endian val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a little-endian CPU, + * unchanged otherwise. + */ #define retro_be_to_cpu16(val) swap_if_little16(val) /** - * retro_be_to_cpu32: - * @val : unsigned 32-bit value - * - * Convert unsigned 32-bit value from big-endian to native. + * Converts the given unsigned 32-bit integer from big-endian to host-native order if necessary. * - * Returns: Native representation of big-endian val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a little-endian CPU, + * unchanged otherwise. + */ #define retro_be_to_cpu32(val) swap_if_little32(val) /** - * retro_be_to_cpu64: - * @val : unsigned 64-bit value + * Converts the given unsigned 64-bit integer from big-endian to host-native order if necessary. * - * Convert unsigned 64-bit value from big-endian to native. - * - * Returns: Native representation of big-endian val. - **/ - + * @param val The value to convert if necessary. + * @return \c val byteswapped if on a little-endian CPU, + * unchanged otherwise. + */ #define retro_be_to_cpu64(val) swap_if_little64(val) #ifdef __GNUC__ -/* This attribute means that the same memory may be referred through - pointers to different size of the object (aliasing). E.g. that u8 * - and u32 * may actually be pointing to the same object. */ +/** + * This attribute indicates that pointers to this type may alias + * to pointers of any other type, similar to \c void* or \c char*. + */ #define MAY_ALIAS __attribute__((__may_alias__)) #else #define MAY_ALIAS @@ -410,8 +382,22 @@ struct retro_unaligned_uint64_s } MAY_ALIAS; #pragma pack(pop) +/** + * A wrapper around a \c uint16_t that allows unaligned access + * where supported by the compiler. + */ typedef struct retro_unaligned_uint16_s retro_unaligned_uint16_t; + +/** + * A wrapper around a \c uint32_t that allows unaligned access + * where supported by the compiler. + */ typedef struct retro_unaligned_uint32_s retro_unaligned_uint32_t; + +/** + * A wrapper around a \c uint64_t that allows unaligned access + * where supported by the compiler. + */ typedef struct retro_unaligned_uint64_s retro_unaligned_uint64_t; /* L-value references to unaligned pointers. */ @@ -420,157 +406,175 @@ typedef struct retro_unaligned_uint64_s retro_unaligned_uint64_t; #define retro_unaligned64(p) (((retro_unaligned_uint64_t *)p)->val) /** - * retro_get_unaligned_16be: - * @addr : pointer to unsigned 16-bit value + * Reads a 16-bit unsigned integer from the given address + * and converts it from big-endian to host-native order (if necessary), + * regardless of the CPU's alignment requirements. * - * Convert unsigned unaligned 16-bit value from big-endian to native. - * - * Returns: Native representation of big-endian val. - **/ - + * @param addr The address of the integer to read. + * Does not need to be divisible by 2 + * the way a \c uint16_t* usually would be. + * @return The first two bytes of \c addr as a 16-bit unsigned integer, + * byteswapped from big-endian to host-native order if necessary. + */ static INLINE uint16_t retro_get_unaligned_16be(void *addr) { return retro_be_to_cpu16(retro_unaligned16(addr)); } /** - * retro_get_unaligned_32be: - * @addr : pointer to unsigned 32-bit value - * - * Convert unsigned unaligned 32-bit value from big-endian to native. + * Reads a 32-bit unsigned integer from the given address + * and converts it from big-endian to host-native order (if necessary), + * regardless of the CPU's alignment requirements. * - * Returns: Native representation of big-endian val. - **/ - + * @param addr The address of the integer to read. + * Does not need to be divisible by 4 + * the way a \c uint32_t* usually would be. + * @return The first four bytes of \c addr as a 32-bit unsigned integer, + * byteswapped from big-endian to host-native order if necessary. + */ static INLINE uint32_t retro_get_unaligned_32be(void *addr) { return retro_be_to_cpu32(retro_unaligned32(addr)); } /** - * retro_get_unaligned_64be: - * @addr : pointer to unsigned 64-bit value - * - * Convert unsigned unaligned 64-bit value from big-endian to native. + * Reads a 64-bit unsigned integer from the given address + * and converts it from big-endian to host-native order (if necessary), + * regardless of the CPU's alignment requirements. * - * Returns: Native representation of big-endian val. - **/ - + * @param addr The address of the integer to read. + * Does not need to be divisible by 8 + * the way a \c uint64_t* usually would be. + * @return The first eight bytes of \c addr as a 64-bit unsigned integer, + * byteswapped from big-endian to host-native order if necessary. + */ static INLINE uint64_t retro_get_unaligned_64be(void *addr) { return retro_be_to_cpu64(retro_unaligned64(addr)); } /** - * retro_get_unaligned_16le: - * @addr : pointer to unsigned 16-bit value + * Reads a 16-bit unsigned integer from the given address + * and converts it from little-endian to host-native order (if necessary), + * regardless of the CPU's alignment requirements. * - * Convert unsigned unaligned 16-bit value from little-endian to native. - * - * Returns: Native representation of little-endian val. - **/ - + * @param addr The address of the integer to read. + * Does not need to be divisible by 2 + * the way a \c uint16_t* usually would be. + * @return The first two bytes of \c addr as a 16-bit unsigned integer, + * byteswapped from little-endian to host-native order if necessary. + */ static INLINE uint16_t retro_get_unaligned_16le(void *addr) { return retro_le_to_cpu16(retro_unaligned16(addr)); } /** - * retro_get_unaligned_32le: - * @addr : pointer to unsigned 32-bit value - * - * Convert unsigned unaligned 32-bit value from little-endian to native. + * Reads a 32-bit unsigned integer from the given address + * and converts it from little-endian to host-native order (if necessary), + * regardless of the CPU's alignment requirements. * - * Returns: Native representation of little-endian val. - **/ - + * @param addr The address of the integer to read. + * Does not need to be divisible by 4 + * the way a \c uint32_t* usually would be. + * @return The first four bytes of \c addr as a 32-bit unsigned integer, + * byteswapped from little-endian to host-native order if necessary. + */ static INLINE uint32_t retro_get_unaligned_32le(void *addr) { return retro_le_to_cpu32(retro_unaligned32(addr)); } /** - * retro_get_unaligned_64le: - * @addr : pointer to unsigned 64-bit value + * Reads a 64-bit unsigned integer from the given address + * and converts it from little-endian to host-native order (if necessary), + * regardless of the CPU's alignment requirements. * - * Convert unsigned unaligned 64-bit value from little-endian to native. - * - * Returns: Native representation of little-endian val. - **/ - + * @param addr The address of the integer to read. + * Does not need to be divisible by 8 + * the way a \c uint64_t* usually would be. + * @return The first eight bytes of \c addr as a 64-bit unsigned integer, + * byteswapped from little-endian to host-native order if necessary. + */ static INLINE uint64_t retro_get_unaligned_64le(void *addr) { return retro_le_to_cpu64(retro_unaligned64(addr)); } /** - * retro_set_unaligned_16le: - * @addr : pointer to unsigned 16-bit value - * @val : value to store - * - * Convert native value to unsigned unaligned 16-bit little-endian value + * Writes a 16-bit unsigned integer to the given address + * (converted to little-endian order if necessary), + * regardless of the CPU's alignment requirements. * - **/ - + * @param addr The address to write the integer to. + * Does not need to be divisible by 2 + * the way a \c uint16_t* usually would be. + * @param v The value to write. + */ static INLINE void retro_set_unaligned_16le(void *addr, uint16_t v) { retro_unaligned16(addr) = retro_cpu_to_le16(v); } /** - * retro_set_unaligned_32le: - * @addr : pointer to unsigned 32-bit value - * @val : value to store - * - * Convert native value to unsigned unaligned 32-bit little-endian value + * Writes a 32-bit unsigned integer to the given address + * (converted to little-endian order if necessary), + * regardless of the CPU's alignment requirements. * - **/ - + * @param addr The address to write the integer to. + * Does not need to be divisible by 4 + * the way a \c uint32_t* usually would be. + * @param v The value to write. + */ static INLINE void retro_set_unaligned_32le(void *addr, uint32_t v) { retro_unaligned32(addr) = retro_cpu_to_le32(v); } /** - * retro_set_unaligned_32le: - * @addr : pointer to unsigned 32-bit value - * @val : value to store + * Writes a 64-bit unsigned integer to the given address + * (converted to little-endian order if necessary), + * regardless of the CPU's alignment requirements. * - * Convert native value to unsigned unaligned 32-bit little-endian value - * - **/ - + * @param addr The address to write the integer to. + * Does not need to be divisible by 8 + * the way a \c uint64_t* usually would be. + * @param v The value to write. + */ static INLINE void retro_set_unaligned_64le(void *addr, uint64_t v) { retro_unaligned64(addr) = retro_cpu_to_le64(v); } /** - * retro_set_unaligned_16be: - * @addr : pointer to unsigned 16-bit value - * @val : value to store - * - * Convert native value to unsigned unaligned 16-bit big-endian value + * Writes a 16-bit unsigned integer to the given address + * (converted to big-endian order if necessary), + * regardless of the CPU's alignment requirements. * - **/ - + * @param addr The address to write the integer to. + * Does not need to be divisible by 2 + * the way a \c uint16_t* usually would be. + * @param v The value to write. + */ static INLINE void retro_set_unaligned_16be(void *addr, uint16_t v) { retro_unaligned16(addr) = retro_cpu_to_be16(v); } /** - * retro_set_unaligned_32be: - * @addr : pointer to unsigned 32-bit value - * @val : value to store - * - * Convert native value to unsigned unaligned 32-bit big-endian value + * Writes a 32-bit unsigned integer to the given address + * (converted to big-endian order if necessary), + * regardless of the CPU's alignment requirements. * - **/ - + * @param addr The address to write the integer to. + * Does not need to be divisible by 4 + * the way a \c uint32_t* usually would be. + * @param v The value to write. + */ static INLINE void retro_set_unaligned_32be(void *addr, uint32_t v) { retro_unaligned32(addr) = retro_cpu_to_be32(v); } /** - * retro_set_unaligned_32be: - * @addr : pointer to unsigned 32-bit value - * @val : value to store + * Writes a 64-bit unsigned integer to the given address + * (converted to big-endian order if necessary), + * regardless of the CPU's alignment requirements. * - * Convert native value to unsigned unaligned 32-bit big-endian value - * - **/ - + * @param addr The address to write the integer to. + * Does not need to be divisible by 8 + * the way a \c uint64_t* usually would be. + * @param v The value to write. + */ static INLINE void retro_set_unaligned_64be(void *addr, uint64_t v) { retro_unaligned64(addr) = retro_cpu_to_be64(v); } diff --git a/platform/libretro/libretro-common/include/retro_inline.h b/platform/libretro/libretro-common/include/retro_inline.h index b27d6dd6d..a9e41bc8e 100644 --- a/platform/libretro/libretro-common/include/retro_inline.h +++ b/platform/libretro/libretro-common/include/retro_inline.h @@ -25,6 +25,12 @@ #ifndef INLINE +/** + * Cross-platform inline specifier. + * + * Expands to something like \c __inline or \c inline, + * depending on the compiler. + */ #if defined(_WIN32) || defined(__INTEL_COMPILER) #define INLINE __inline #elif defined(__STDC_VERSION__) && __STDC_VERSION__>=199901L diff --git a/platform/libretro/libretro-common/include/retro_miscellaneous.h b/platform/libretro/libretro-common/include/retro_miscellaneous.h index 7fdbbf066..24b18c938 100644 --- a/platform/libretro/libretro-common/include/retro_miscellaneous.h +++ b/platform/libretro/libretro-common/include/retro_miscellaneous.h @@ -49,6 +49,17 @@ #include #endif +#ifdef IOS +#include +#endif + +/** + * Computes the bitwise OR of two bit arrays. + * + * @param a[in,out] The first bit array, and the location of the result. + * @param b[in] The second bit array. + * @param count The length of each bit array, in 32-bit words. + */ static INLINE void bits_or_bits(uint32_t *a, uint32_t *b, uint32_t count) { uint32_t i; @@ -56,6 +67,14 @@ static INLINE void bits_or_bits(uint32_t *a, uint32_t *b, uint32_t count) a[i] |= b[i]; } +/** + * Clears every bit in \c a that is set in \c b. + * + * @param a[in,out] The bit array to modify. + * @param b[in] The bit array to use for reference. + * @param count The length of each bit array, in 32-bit words + * (\em not bits or bytes). + */ static INLINE void bits_clear_bits(uint32_t *a, uint32_t *b, uint32_t count) { uint32_t i; @@ -63,6 +82,15 @@ static INLINE void bits_clear_bits(uint32_t *a, uint32_t *b, uint32_t count) a[i] &= ~b[i]; } +/** + * Checks if any bits in \c ptr are set. + * + * @param ptr The bit array to check. + * @param count The length of the buffer pointed to by \c ptr, in 32-bit words + * (\em not bits or bytes). + * @return \c true if any bit in \c ptr is set, + * \c false if all bits are clear (zero). + */ static INLINE bool bits_any_set(uint32_t* ptr, uint32_t count) { uint32_t i; @@ -74,52 +102,261 @@ static INLINE bool bits_any_set(uint32_t* ptr, uint32_t count) return false; } +/** + * Checks if any bits in \c a are different from those in \c b. + * + * @param a The first bit array to compare. + * @param b The second bit array to compare. + * @param count The length of each bit array, in 32-bit words + * (\em not bits or bytes). + * @return \c true if \c and \c differ by at least one bit, + * \c false if they're both identical. + */ +static INLINE bool bits_any_different(uint32_t *a, uint32_t *b, uint32_t count) +{ + uint32_t i; + for (i = 0; i < count; i++) + { + if (a[i] != b[i]) + return true; + } + return false; +} + +/** + * An upper limit for the length of a path (including the filename). + * If a path is longer than this, it may not work properly. + * This value may vary by platform. + */ + +#if defined(_XBOX1) || defined(_3DS) || defined(PSP) || defined(PS2) || defined(GEKKO)|| defined(WIIU) || defined(__PSL1GHT__) || defined(__PS3__) || defined(HAVE_EMSCRIPTEN) + #ifndef PATH_MAX_LENGTH -#if defined(_XBOX1) || defined(_3DS) || defined(PSP) || defined(PS2) || defined(GEKKO)|| defined(WIIU) || defined(ORBIS) #define PATH_MAX_LENGTH 512 -#elif defined(__PS3__) -#define PATH_MAX_LENGTH 1024 +#endif + +#ifndef DIR_MAX_LENGTH +#define DIR_MAX_LENGTH 256 +#endif + +/** + * An upper limit for the length of a file or directory (excluding parent directories). + * If a path has a component longer than this, it may not work properly. + */ +#ifndef NAME_MAX_LENGTH +#define NAME_MAX_LENGTH 128 +#endif + #else -#define PATH_MAX_LENGTH 4096 + +#ifndef PATH_MAX_LENGTH +#define PATH_MAX_LENGTH 2048 #endif + +#ifndef DIR_MAX_LENGTH +#define DIR_MAX_LENGTH 1024 #endif +/** + * An upper limit for the length of a file or directory (excluding parent directories). + * If a path has a component longer than this, it may not work properly. + */ #ifndef NAME_MAX_LENGTH #define NAME_MAX_LENGTH 256 #endif +#endif + + #ifndef MAX +/** + * @return \c a or \c b, whichever is larger. + */ #define MAX(a, b) ((a) > (b) ? (a) : (b)) #endif #ifndef MIN +/** + * @return \c a or \c b, whichever is smaller. + */ #define MIN(a, b) ((a) < (b) ? (a) : (b)) #endif +/** + * Gets the number of elements in an array whose size is known at compile time. + * @param a An array of fixed length. + * @return The number of elements in \c a. + */ #define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0])) +/** @defgroup BITS Bit Arrays + * + * @{ + */ + #define BITS_GET_ELEM(a, i) ((a).data[i]) #define BITS_GET_ELEM_PTR(a, i) ((a)->data[i]) +/** @defgroup BIT_ Arbitrary-length Bit Arrays + * + * @{ + */ + +/** + * Sets a particular bit within a bit array to 1. + * + * @param a A \c uint8_t array, + * treated here as a bit vector. + * @param bit Index of the bit to set, where 0 is the least significant. + */ #define BIT_SET(a, bit) ((a)[(bit) >> 3] |= (1 << ((bit) & 7))) + +/** + * Clears a particular bit within a bit array. + * + * @param a A \c uint8_t array, + * treated here as a bit vector. + * @param bit Index of the bit to clear, where 0 is the least significant. + */ #define BIT_CLEAR(a, bit) ((a)[(bit) >> 3] &= ~(1 << ((bit) & 7))) + +/** + * Gets the value of a particular bit within a bit array. + * + * @param a A \c uint8_t array, + * treated here as a bit vector. + * @param bit Index of the bit to get, where 0 is the least significant. + * @return The value of the bit at the specified index. + */ #define BIT_GET(a, bit) (((a)[(bit) >> 3] >> ((bit) & 7)) & 1) +/** @} */ + +/** @defgroup BIT16 16-bit Bit Arrays + * + * @{ + */ + +/** + * Sets a particular bit within a 16-bit integer to 1. + * @param a An unsigned 16-bit integer, + * treated as a bit array. + * @param bit Index of the bit to set, where 0 is the least significant and 15 is the most. + */ #define BIT16_SET(a, bit) ((a) |= (1 << ((bit) & 15))) + +/** + * Clears a particular bit within a 16-bit integer. + * + * @param a An unsigned 16-bit integer, + * treated as a bit array. + * @param bit Index of the bit to clear, where 0 is the least significant and 15 is the most. + */ #define BIT16_CLEAR(a, bit) ((a) &= ~(1 << ((bit) & 15))) + +/** + * Gets the value of a particular bit within a 16-bit integer. + * + * @param a An unsigned 16-bit integer, + * treated as a bit array. + * @param bit Index of the bit to get, where 0 is the least significant and 15 is the most. + * @return The value of the bit at the specified index. + */ #define BIT16_GET(a, bit) (((a) >> ((bit) & 15)) & 1) + +/** + * Clears all bits in a 16-bit bitmask. + */ #define BIT16_CLEAR_ALL(a) ((a) = 0) +/** @} */ + +/** @defgroup BIT32 32-bit Bit Arrays + * + * @{ + */ + +/** + * Sets a particular bit within a 32-bit integer to 1. + * + * @param a An unsigned 32-bit integer, + * treated as a bit array. + * @param bit Index of the bit to set, where 0 is the least significant and 31 is the most. + */ #define BIT32_SET(a, bit) ((a) |= (UINT32_C(1) << ((bit) & 31))) + +/** + * Clears a particular bit within a 32-bit integer. + * + * @param a An unsigned 32-bit integer, + * treated as a bit array. + * @param bit Index of the bit to clear, where 0 is the least significant and 31 is the most. + */ #define BIT32_CLEAR(a, bit) ((a) &= ~(UINT32_C(1) << ((bit) & 31))) + +/** + * Gets the value of a particular bit within a 32-bit integer. + * + * @param a An unsigned 32-bit integer, + * treated as a bit array. + * @param bit Index of the bit to get, where 0 is the least significant and 31 is the most. + * @return The value of the bit at the specified index. + */ #define BIT32_GET(a, bit) (((a) >> ((bit) & 31)) & 1) + +/** + * Clears all bits in a 32-bit bitmask. + * + * @param a An unsigned 32-bit integer, + * treated as a bit array. + */ #define BIT32_CLEAR_ALL(a) ((a) = 0) +/** @} */ + +/** + * @defgroup BIT64 64-bit Bit Arrays + * @{ + */ + +/** + * Sets a particular bit within a 64-bit integer to 1. + * + * @param a An unsigned 64-bit integer, + * treated as a bit array. + * @param bit Index of the bit to set, where 0 is the least significant and 63 is the most. + */ #define BIT64_SET(a, bit) ((a) |= (UINT64_C(1) << ((bit) & 63))) + +/** + * Clears a particular bit within a 64-bit integer. + * + * @param a An unsigned 64-bit integer, + * treated as a bit array. + * @param bit Index of the bit to clear, where 0 is the least significant and 63 is the most. + */ #define BIT64_CLEAR(a, bit) ((a) &= ~(UINT64_C(1) << ((bit) & 63))) + +/** + * Gets the value of a particular bit within a 64-bit integer. + * + * @param a An unsigned 64-bit integer, + * treated as a bit array. + * @param bit Index of the bit to get, where 0 is the least significant and 63 is the most. + * @return The value of the bit at the specified index. + */ #define BIT64_GET(a, bit) (((a) >> ((bit) & 63)) & 1) + +/** + * Clears all bits in a 64-bit bitmask. + * + * @param a An unsigned 64-bit integer, + * treated as a bit array. + */ #define BIT64_CLEAR_ALL(a) ((a) = 0) +/** @} */ + #define BIT128_SET(a, bit) ((a).data[(bit) >> 5] |= (UINT32_C(1) << ((bit) & 31))) #define BIT128_CLEAR(a, bit) ((a).data[(bit) >> 5] &= ~(UINT32_C(1) << ((bit) & 31))) #define BIT128_GET(a, bit) (((a).data[(bit) >> 5] >> ((bit) & 31)) & 1) @@ -130,24 +367,98 @@ static INLINE bool bits_any_set(uint32_t* ptr, uint32_t count) #define BIT128_GET_PTR(a, bit) BIT128_GET(*a, bit) #define BIT128_CLEAR_ALL_PTR(a) BIT128_CLEAR_ALL(*a) +/** + * Sets a single bit from a 256-bit \c retro_bits_t to 1. + * + * @param a A 256-bit \c retro_bits_t. + * @param bit Index of the bit to set, + * where 0 is the least significant and 255 is the most. + */ #define BIT256_SET(a, bit) BIT128_SET(a, bit) + +/** + * Clears a single bit from a 256-bit \c retro_bits_t. + * + * @param a A 256-bit \c retro_bits_t. + * @param bit Index of the bit to clear, + * where 0 is the least significant and 255 is the most. + */ #define BIT256_CLEAR(a, bit) BIT128_CLEAR(a, bit) + +/** + * Gets the value of a single bit from a 256-bit \c retro_bits_t. + * + * @param a A 256-bit \c retro_bits_t. + * @param bit Index of the bit to get, + * where 0 is the least significant and 255 is the most. + * @return The value of the bit at the specified index. + */ #define BIT256_GET(a, bit) BIT128_GET(a, bit) + +/** + * Clears all bits in a 256-bit \c retro_bits_t. + * + * @param a A 256-bit \c retro_bits_t. + */ #define BIT256_CLEAR_ALL(a) BIT128_CLEAR_ALL(a) +/** Variant of BIT256_SET() that takes a pointer to a \c retro_bits_t. */ #define BIT256_SET_PTR(a, bit) BIT256_SET(*a, bit) + +/** Variant of BIT256_CLEAR() that takes a pointer to a \c retro_bits_t. */ #define BIT256_CLEAR_PTR(a, bit) BIT256_CLEAR(*a, bit) + +/** Variant of BIT256_GET() that takes a pointer to a \c retro_bits_t. */ #define BIT256_GET_PTR(a, bit) BIT256_GET(*a, bit) + +/** Variant of BIT256_CLEAR_ALL() that takes a pointer to a \c retro_bits_t. */ #define BIT256_CLEAR_ALL_PTR(a) BIT256_CLEAR_ALL(*a) +/** + * Sets a single bit from a 512-bit \c retro_bits_512_t to 1. + * + * @param a A 512-bit \c retro_bits_512_t. + * @param bit Index of the bit to set, + * where 0 is the least significant and 511 is the most. + */ #define BIT512_SET(a, bit) BIT256_SET(a, bit) + +/** + * Clears a single bit from a 512-bit \c retro_bits_512_t. + * + * @param a A 512-bit \c retro_bits_512_t. + * @param bit Index of the bit to clear, + * where 0 is the least significant and 511 is the most. + */ #define BIT512_CLEAR(a, bit) BIT256_CLEAR(a, bit) + +/** + * Gets the value of a single bit from a 512-bit \c retro_bits_512_t. + * + * @param a A 512-bit \c retro_bits_512_t. + * @param bit Index of the bit to get, + * where 0 is the least significant and 511 is the most. + * @return The value of the bit at the specified index. + */ #define BIT512_GET(a, bit) BIT256_GET(a, bit) + +/** + * Clears all bits in a 512-bit \c retro_bits_512_t. + * + * @param a A 512-bit \c retro_bits_512_t. + */ #define BIT512_CLEAR_ALL(a) BIT256_CLEAR_ALL(a) +/** Variant of BIT512_SET() that takes a pointer to a \c retro_bits_512_t. */ #define BIT512_SET_PTR(a, bit) BIT512_SET(*a, bit) + +/** Variant of BIT512_CLEAR() that takes a pointer to a \c retro_bits_512_t. */ #define BIT512_CLEAR_PTR(a, bit) BIT512_CLEAR(*a, bit) + +/** Variant of BIT512_GET() that takes a pointer to a \c retro_bits_512_t. */ #define BIT512_GET_PTR(a, bit) BIT512_GET(*a, bit) + +/** Variant of BIT512_CLEAR_ALL() that takes a pointer to a \c retro_bits_512_t. */ #define BIT512_CLEAR_ALL_PTR(a) BIT512_CLEAR_ALL(*a) #define BITS_COPY16_PTR(a,bits) \ @@ -170,18 +481,23 @@ static INLINE bool bits_any_set(uint32_t* ptr, uint32_t count) } /* Helper macros and struct to keep track of many booleans. */ -/* This struct has 256 bits. */ + +/** A 256-bit boolean array. */ typedef struct { + /** @private 256 bits. Not intended for direct use. */ uint32_t data[8]; } retro_bits_t; -/* This struct has 512 bits. */ +/** A 512-bit boolean array. */ typedef struct { + /** @private 512 bits. Not intended for direct use. */ uint32_t data[16]; } retro_bits_512_t; +/** @} */ + #ifdef _WIN32 # ifdef _WIN64 # define PRI_SIZET PRIu64 diff --git a/platform/libretro/libretro-common/include/streams/file_stream.h b/platform/libretro/libretro-common/include/streams/file_stream.h index 5276f87a2..c76968acc 100644 --- a/platform/libretro/libretro-common/include/streams/file_stream.h +++ b/platform/libretro/libretro-common/include/streams/file_stream.h @@ -38,80 +38,377 @@ #include #include +/** @defgroup file_stream File Streams + * + * All functions in this header will use the VFS interface set in \ref filestream_vfs_init if possible, + * or else they will fall back to built-in equivalents. + * + * @note These functions are modeled after those in the C standard library + * (and may even use them internally), + * but identical behavior is not guaranteed. + * + * @{ + */ + +/** + * The minimum version of the VFS interface required by the \c filestream functions. + */ #define FILESTREAM_REQUIRED_VFS_VERSION 2 RETRO_BEGIN_DECLS +/** + * Opaque handle to a file stream. + * @warning This is not interchangeable with \c FILE* or \c retro_vfs_file_handle. + */ typedef struct RFILE RFILE; #define FILESTREAM_REQUIRED_VFS_VERSION 2 +/** + * Initializes the \c filestream functions to use the VFS interface provided by the frontend. + * Optional; if not called, all \c filestream functions + * will use libretro-common's built-in implementations. + * + * @param vfs_info The VFS interface returned by the frontend. + * If \c vfs_info::iface (but \em not \c vfs_info itself) is \c NULL, + * then libretro-common's built-in VFS implementation will be used. + */ void filestream_vfs_init(const struct retro_vfs_interface_info* vfs_info); +/** + * Returns the size of the given file, in bytes. + * + * @param stream The open file to query. + * @return The size of \c stream in bytes, + * or -1 if there was an error. + * @see retro_vfs_size_t + */ int64_t filestream_get_size(RFILE *stream); +/** + * Sets the size of the given file, + * truncating or extending it as necessary. + * + * @param stream The file to resize. + * @param length The new size of \c stream, in bytes. + * @return 0 if the resize was successful, + * or -1 if there was an error. + * @see retro_vfs_truncate_t + */ int64_t filestream_truncate(RFILE *stream, int64_t length); /** - * filestream_open: - * @path : path to file - * @mode : file mode to use when opening (read/write) - * @bufsize : optional buffer size (-1 or 0 to use default) + * Opens a file for reading or writing. * - * Opens a file for reading or writing, depending on the requested mode. - * Returns a pointer to an RFILE if opened successfully, otherwise NULL. - **/ + * @param path Path to the file to open. + * Should be in the format described in \ref GET_VFS_INTERFACE. + * @param mode The mode to open the file in. + * Should be one or more of the flags in \refitem RETRO_VFS_FILE_ACCESS OR'd together, + * and \c RETRO_VFS_FILE_ACCESS_READ or \c RETRO_VFS_FILE_ACCESS_WRITE + * (or both) must be included. + * @param hints Optional hints to pass to the frontend. + * + * @return The opened file, or \c NULL if there was an error. + * Must be cleaned up with \c filestream_close when no longer needed. + * @see retro_vfs_open_t + */ RFILE* filestream_open(const char *path, unsigned mode, unsigned hints); +/** + * Sets the current position of the file stream. + * Use this to read specific sections of a file. + * + * @param stream The file to set the stream position of. + * @param offset The new stream position, in bytes. + * @param seek_position The position to seek from. + * Should be one of the values in \refitem RETRO_VFS_SEEK_POSITION. + * @return The new stream position in bytes relative to the beginning, + * or -1 if there was an error. + * @see RETRO_VFS_SEEK_POSITION + * @see retro_vfs_seek_t + */ int64_t filestream_seek(RFILE *stream, int64_t offset, int seek_position); +/** + * Reads data from the given file into a buffer. + * If the read is successful, + * the file's stream position will advance by the number of bytes read. + * + * @param stream The file to read from. + * @param data The buffer in which to store the read data. + * @param len The size of \c data, in bytes. + * @return The number of bytes read, + * or -1 if there was an error. + * May be less than \c len, but never more. + * @see retro_vfs_read_t + */ int64_t filestream_read(RFILE *stream, void *data, int64_t len); +/** + * Writes data from a buffer to the given file. + * If the write is successful, + * the file's stream position will advance by the number of bytes written. + * + * @param stream The file to write to. + * @param data The buffer containing the data to write. + * @param len The size of \c data, in bytes. + * @return The number of bytes written, + * or -1 if there was an error. + * May be less than \c len, but never more. + * @see retro_vfs_write_t + */ int64_t filestream_write(RFILE *stream, const void *data, int64_t len); +/** + * Returns the current position of the given file in bytes. + * + * @param stream The file to return the stream position for. + * @return The current stream position in bytes relative to the beginning, + * or -1 if there was an error. + * @see retro_vfs_tell_t + */ int64_t filestream_tell(RFILE *stream); +/** + * Rewinds the given file to the beginning. + * Equivalent to filestream_seek(stream, 0, RETRO_VFS_SEEK_POSITION_START). + + * @param stream The file to rewind. + * May be \c NULL, in which case this function does nothing. + */ void filestream_rewind(RFILE *stream); +/** + * Closes the given file. + * + * @param stream The file to close. + * This should have been created with \c filestream_open. + * Behavior is undefined if \c NULL. + * @return 0 if the file was closed successfully, + * or -1 if there was an error. + * @post \c stream is no longer valid and should not be used, + * even if this function fails. + * @see retro_vfs_close_t + */ int filestream_close(RFILE *stream); +/** + * Opens a file, reads its contents into a newly-allocated buffer, + * then closes it. + * + * @param path[in] Path to the file to read. + * Should be in the format described in \ref GET_VFS_INTERFACE. + * @param buf[out] A pointer to the address of the newly-allocated buffer. + * The buffer will contain the entirety of the file at \c path. + * Will be allocated with \c malloc and must be freed with \c free. + * @param len[out] Pointer to the size of the buffer in bytes. + * May be \c NULL, in which case the length is not written. + * Value is unspecified if this function fails. + * @return 1 if the file was read successfully, + * 0 if there was an error. + * @see filestream_write_file + */ int64_t filestream_read_file(const char *path, void **buf, int64_t *len); +/** + * Reads a line of text from the given file, + * up to a given length. + * + * Will read to the next newline or until the buffer is full, + * whichever comes first. + * + * @param stream The file to read from. + * @param s The buffer to write the retrieved line to. + * Will contain at most \c len - 1 characters + * plus a null terminator. + * The newline character (if any) will not be included. + * The line delimiter must be Unix-style (\c '\n'). + * Carriage returns (\c '\r') will not be treated specially. + * @param len The length of the buffer \c s, in bytes. + * @return \s if successful, \c NULL if there was an error. + */ char* filestream_gets(RFILE *stream, char *s, size_t len); +/** + * Reads a single character from the given file. + * + * @param stream The file to read from. + * @return The character read, or -1 upon reaching the end of the file. + */ int filestream_getc(RFILE *stream); +/** + * Reads formatted text from the given file, + * with arguments provided as a standard \c va_list. + * + * @param stream The file to read from. + * @param format The string to write, possibly including scanf-compatible format specifiers. + * @param args Argument list with zero or more elements + * whose values will be updated according to the semantics of \c format. + * @return The number of arguments in \c args that were successfully assigned, + * or -1 if there was an error. + * @see https://en.cppreference.com/w/c/io/fscanf + * @see https://en.cppreference.com/w/c/variadic + */ int filestream_vscanf(RFILE *stream, const char* format, va_list *args); +/** + * Reads formatted text from the given file. + * + * @param stream The file to read from. + * @param format The string to write, possibly including scanf-compatible format specifiers. + * @param ... Zero or more arguments that will be updated according to the semantics of \c format. + * @return The number of arguments in \c ... that were successfully assigned, + * or -1 if there was an error. + * @see https://en.cppreference.com/w/c/io/fscanf + */ int filestream_scanf(RFILE *stream, const char* format, ...); +/** + * Determines if there's any more data left to read from this file. + * + * @param stream The file to check the position of. + * @return -1 if this stream has reached the end of the file, + * 0 if not. + */ int filestream_eof(RFILE *stream); +/** + * Writes the entirety of a given buffer to a file at a given path. + * Any file that already exists will be overwritten. + * + * @param path Path to the file that will be written to. + * @param data The buffer to write to \c path. + * @param size The size of \c data, in bytes. + * @return \c true if the file was written successfully, + * \c false if there was an error. + */ bool filestream_write_file(const char *path, const void *data, int64_t size); +/** + * Writes a single character to the given file. + * + * @param stream The file to write to. + * @param c The character to write. + * @return The character written, + * or -1 if there was an error. + * Will return -1 if \c stream is \c NULL. + */ int filestream_putc(RFILE *stream, int c); +/** + * Writes formatted text to the given file, + * with arguments provided as a standard \c va_list. + * + * @param stream The file to write to. + * @param format The string to write, possibly including printf-compatible format specifiers. + * @param args A list of arguments to be formatted and inserted in the resulting string. + * @return The number of characters written, + * or -1 if there was an error. + * @see https://en.cppreference.com/w/c/io/vfprintf + * @see https://en.cppreference.com/w/c/variadic + */ int filestream_vprintf(RFILE *stream, const char* format, va_list args); +/** + * Writes formatted text to the given file. + * + * @param stream The file to write to. + * @param format The string to write, possibly including printf-compatible format specifiers. + * @param ... Zero or more arguments to be formatted and inserted into the resulting string. + * @return The number of characters written, + * or -1 if there was an error. + * @see https://en.cppreference.com/w/c/io/printf + */ int filestream_printf(RFILE *stream, const char* format, ...); +/** + * Checks if there was an error in using the given file stream. + * + * @param stream The file stream to check for errors. + * @return \c true if there was an error in using this stream, + * \c false if not or if \c stream is \c NULL. + */ int filestream_error(RFILE *stream); +/** + * Flushes pending writes to the operating system's file layer. + * There is no guarantee that pending writes will be written to disk immediately. + * + * @param stream The file to flush. + * @return 0 if the flush was successful, + * or -1 if there was an error. + * @see retro_vfs_flush_t + */ int filestream_flush(RFILE *stream); +/** + * Deletes the file at the given path. + * If the file is open by any process, + * the behavior is platform-specific. + * + * @note This function might or might not delete directories recursively, + * depending on the platform and the underlying VFS implementation. + * + * @param path The file to delete. + * @return 0 if the file was deleted successfully, + * or -1 if there was an error. + * @see retro_vfs_remove_t + */ int filestream_delete(const char *path); +/** + * Moves a file to a new location, with a new name. + * + * @param old_path Path to the file to rename. + * @param new_path The target name and location of the file. + * @return 0 if the file was renamed successfully, + * or -1 if there was an error. + * @see retro_vfs_rename_t + */ int filestream_rename(const char *old_path, const char *new_path); +/** + * Get the path that was used to open a file. + * + * @param stream The file to get the path of. + * @return The path that was used to open \c stream, + * or \c NULL if there was an error. + * The string is owned by \c stream and must not be modified or freed by the caller. + */ const char* filestream_get_path(RFILE *stream); +/** + * Determines if a file exists at the given path. + * + * @param path The path to check for existence. + * @return \c true if a file exists at \c path, + * \c false if not or if \c path is \c NULL or empty. + */ bool filestream_exists(const char *path); -/* Returned pointer must be freed by the caller. */ +/** + * Reads a line from the given file into a newly-allocated buffer. + * + * @param stream The file to read from. + * @return Pointer to the line read from \c stream, + * or \c NULL if there was an error. + * Must be freed with \c free when no longer needed. + */ char* filestream_getline(RFILE *stream); +/** + * Returns the open file handle + * that was originally returned by the VFS interface. + * + * @param stream File handle returned by \c filestream_open. + * @return The file handle returned by the underlying VFS implementation. + */ libretro_vfs_implementation_file* filestream_get_vfs_handle(RFILE *stream); RETRO_END_DECLS +/** @} */ + #endif diff --git a/platform/libretro/libretro-common/include/streams/file_stream_transforms.h b/platform/libretro/libretro-common/include/streams/file_stream_transforms.h index 327e2184c..60e138827 100644 --- a/platform/libretro/libretro-common/include/streams/file_stream_transforms.h +++ b/platform/libretro/libretro-common/include/streams/file_stream_transforms.h @@ -28,10 +28,23 @@ #include #include +/** + * @file file_stream_transforms.h + * + * Contains macros that redirect standard C I/O functions + * to libretro's own file stream API. + * Useful when porting an existing emulator to a core. + * To use these functions without overriding the standard I/O functions, + * define \c SKIP_STDIO_REDEFINES before including this header. + * + * @see https://man7.org/linux/man-pages/man3/stdio.3.html + */ + RETRO_BEGIN_DECLS #ifndef SKIP_STDIO_REDEFINES +/** @see https://en.cppreference.com/w/c/io/FILE */ #define FILE RFILE #undef fopen @@ -66,34 +79,48 @@ RETRO_BEGIN_DECLS #endif +/** @see https://en.cppreference.com/w/c/io/fopen */ RFILE* rfopen(const char *path, const char *mode); +/** @see https://en.cppreference.com/w/c/io/fclose */ int rfclose(RFILE* stream); +/** @see https://en.cppreference.com/w/c/io/ftell */ int64_t rftell(RFILE* stream); +/** @see https://en.cppreference.com/w/c/io/fseek */ int64_t rfseek(RFILE* stream, int64_t offset, int origin); +/** @see https://en.cppreference.com/w/c/io/fread */ int64_t rfread(void* buffer, size_t elem_size, size_t elem_count, RFILE* stream); +/** @see https://en.cppreference.com/w/c/io/fgets */ char *rfgets(char *buffer, int maxCount, RFILE* stream); +/** @see https://en.cppreference.com/w/c/io/fgetc */ int rfgetc(RFILE* stream); +/** @see https://en.cppreference.com/w/c/io/fwrite */ int64_t rfwrite(void const* buffer, size_t elem_size, size_t elem_count, RFILE* stream); +/** @see https://en.cppreference.com/w/c/io/fputc */ int rfputc(int character, RFILE * stream); +/** @see https://en.cppreference.com/w/c/io/fflush */ int64_t rfflush(RFILE * stream); +/** @see https://en.cppreference.com/w/c/io/fprintf */ int rfprintf(RFILE * stream, const char * format, ...); +/** @see https://en.cppreference.com/w/c/io/ferror */ int rferror(RFILE* stream); +/** @see https://en.cppreference.com/w/c/io/feof */ int rfeof(RFILE* stream); +/** @see https://en.cppreference.com/w/c/io/fscanf */ int rfscanf(RFILE * stream, const char * format, ...); RETRO_END_DECLS diff --git a/platform/libretro/libretro-common/include/string/stdstring.h b/platform/libretro/libretro-common/include/string/stdstring.h index 2dc00e331..030cc6120 100644 --- a/platform/libretro/libretro-common/include/string/stdstring.h +++ b/platform/libretro/libretro-common/include/string/stdstring.h @@ -48,7 +48,7 @@ RETRO_BEGIN_DECLS #define TOUPPER(c) ((c) & ~(lr_char_props[(unsigned char)(c)] & 0x20)) /* C standard says \f \v are space, but this one disagrees */ -#define ISSPACE(c) (lr_char_props[(unsigned char)(c)] & 0x80) +#define ISSPACE(c) (lr_char_props[(unsigned char)(c)] & 0x80) #define ISDIGIT(c) (lr_char_props[(unsigned char)(c)] & 0x40) #define ISALPHA(c) (lr_char_props[(unsigned char)(c)] & 0x20) @@ -92,16 +92,20 @@ static INLINE bool string_ends_with_size(const char *str, const char *suffix, static INLINE bool string_ends_with(const char *str, const char *suffix) { - if (!str || !suffix) - return false; - return string_ends_with_size(str, suffix, strlen(str), strlen(suffix)); + return str && suffix && string_ends_with_size(str, suffix, strlen(str), strlen(suffix)); } -/* Returns the length of 'str' (c.f. strlen()), but only +/** + * strlen_size: + * + * Leaf function. + * + * @return the length of 'str' (c.f. strlen()), but only * checks the first 'size' characters * - If 'str' is NULL, returns 0 * - If 'str' is not NULL and no '\0' character is found - * in the first 'size' characters, returns 'size' */ + * in the first 'size' characters, returns 'size' + **/ static INLINE size_t strlen_size(const char *str, size_t size) { size_t i = 0; @@ -155,19 +159,43 @@ char *string_to_lower(char *s); char *string_ucwords(char *s); -char *string_replace_substring(const char *in, const char *pattern, - const char *by); +char *string_replace_substring(const char *in, + const char *pattern, size_t pattern_len, + const char *replacement, size_t replacement_len); -/* Remove leading whitespaces */ +/** + * string_trim_whitespace_left: + * + * Remove leading whitespaces + **/ char *string_trim_whitespace_left(char *const s); -/* Remove trailing whitespaces */ +/** + * string_trim_whitespace_right: + * + * Remove trailing whitespaces + **/ char *string_trim_whitespace_right(char *const s); -/* Remove leading and trailing whitespaces */ +/** + * string_trim_whitespace: + * + * Remove leading and trailing whitespaces + **/ char *string_trim_whitespace(char *const s); -/* +/** + * word_wrap: + * @dst : pointer to destination buffer. + * @dst_size : size of destination buffer. + * @src : pointer to input string. + * @src_len : length of @src + * @line_width : max number of characters per line. + * @wideglyph_width : not used, but is necessary to keep + * compatibility with word_wrap_wideglyph(). + * @max_lines : max lines of destination string. + * 0 means no limit. + * * Wraps string specified by 'src' to destination buffer * specified by 'dst' and 'dst_size'. * This function assumes that all glyphs in the string @@ -175,58 +203,57 @@ char *string_trim_whitespace(char *const s); * regular Latin characters - i.e. it will not wrap * correctly any text containing so-called 'wide' Unicode * characters (e.g. CJK languages, emojis, etc.). - * - * @param dst pointer to destination buffer. - * @param dst_size size of destination buffer. - * @param src pointer to input string. - * @param line_width max number of characters per line. - * @param wideglyph_width not used, but is necessary to keep - * compatibility with word_wrap_wideglyph(). - * @param max_lines max lines of destination string. - * 0 means no limit. - */ -void word_wrap(char *dst, size_t dst_size, const char *src, + **/ +size_t word_wrap(char *dst, size_t dst_size, const char *src, size_t src_len, int line_width, int wideglyph_width, unsigned max_lines); -/* - * Wraps string specified by 'src' to destination buffer - * specified by 'dst' and 'dst_size'. +/** + * word_wrap_wideglyph: + * @dst : pointer to destination buffer. + * @dst_size : size of destination buffer. + * @src : pointer to input string. + * @src_len : length of @src + * @line_width : max number of characters per line. + * @wideglyph_width : effective width of 'wide' Unicode glyphs. + * the value here is normalised relative to the + * typical on-screen pixel width of a regular + * Latin character: + * - a regular Latin character is defined to + * have an effective width of 100 + * - wideglyph_width = 100 * (wide_character_pixel_width / latin_character_pixel_width) + * - e.g. if 'wide' Unicode characters in 'src' + * have an on-screen pixel width twice that of + * regular Latin characters, wideglyph_width + * would be 200 + * @max_lines : max lines of destination string. + * 0 means no limit. + * + * Wraps string specified by @src to destination buffer + * specified by @dst and @dst_size. * This function assumes that all glyphs in the string * are: * - EITHER 'non-wide' Unicode glyphs, with an on-screen * pixel width similar to that of regular Latin characters * - OR 'wide' Unicode glyphs (e.g. CJK languages, emojis, etc.) - * with an on-screen pixel width defined by 'wideglyph_width' + * with an on-screen pixel width defined by @wideglyph_width * Note that wrapping may occur in inappropriate locations - * if 'src' string contains 'wide' Unicode characters whose + * if @src string contains 'wide' Unicode characters whose * on-screen pixel width deviates greatly from the set - * 'wideglyph_width' value. - * - * @param dst pointer to destination buffer. - * @param dst_size size of destination buffer. - * @param src pointer to input string. - * @param line_width max number of characters per line. - * @param wideglyph_width effective width of 'wide' Unicode glyphs. - * the value here is normalised relative to the - * typical on-screen pixel width of a regular - * Latin character: - * - a regular Latin character is defined to - * have an effective width of 100 - * - wideglyph_width = 100 * (wide_character_pixel_width / latin_character_pixel_width) - * - e.g. if 'wide' Unicode characters in 'src' - * have an on-screen pixel width twice that of - * regular Latin characters, wideglyph_width - * would be 200 - * @param max_lines max lines of destination string. - * 0 means no limit. - */ -void word_wrap_wideglyph(char *dst, size_t dst_size, const char *src, - int line_width, int wideglyph_width, unsigned max_lines); - -/* Splits string into tokens seperated by 'delim' + * @wideglyph_width value. + **/ +size_t word_wrap_wideglyph( + char *dst, size_t dst_size, + const char *src, size_t src_len, + int line_width, int wideglyph_width, + unsigned max_lines); + +/** + * string_tokenize: + * + * Splits string into tokens separated by @delim * > Returned token string must be free()'d * > Returns NULL if token is not found - * > After each call, 'str' is set to the position after the + * > After each call, @str is set to the position after the * last found token * > Tokens *include* empty strings * Usage example: @@ -239,48 +266,117 @@ void word_wrap_wideglyph(char *dst, size_t dst_size, const char *src, * free(token); * token = NULL; * } - */ + **/ char* string_tokenize(char **str, const char *delim); -/* Removes every instance of character 'c' from 'str' */ +/** + * string_remove_all_chars: + * @str : input string (must be non-NULL, otherwise UB) + * + * Leaf function. + * + * Removes every instance of character @c from @str + **/ void string_remove_all_chars(char *str, char c); -/* Replaces every instance of character 'find' in 'str' - * with character 'replace' */ +/** + * string_replace_all_chars: + * @str : input string (must be non-NULL, otherwise UB) + * @find : character to find + * @replace : character to replace @find with + * + * Hidden non-leaf function cost: + * - Calls strchr (in a loop) + * + * Replaces every instance of character @find in @str + * with character @replace + **/ void string_replace_all_chars(char *str, char find, char replace); -/* Converts string to unsigned integer. - * Returns 0 if string is invalid */ +/** + * string_to_unsigned: + * @str : input string + * + * Converts string to unsigned integer. + * + * @return 0 if string is invalid, otherwise > 0 + **/ unsigned string_to_unsigned(const char *str); -/* Converts hexadecimal string to unsigned integer. +/** + * string_hex_to_unsigned: + * @str : input string (must be non-NULL, otherwise UB) + * + * Converts hexadecimal string to unsigned integer. * Handles optional leading '0x'. - * Returns 0 if string is invalid */ + * + * @return 0 if string is invalid, otherwise > 0 + **/ unsigned string_hex_to_unsigned(const char *str); -char *string_init(const char *src); - -void string_set(char **string, const char *src); - -extern const unsigned char lr_char_props[256]; - -/* Get the total number of occurrences of a character in the given string. */ -int string_count_occurrences_single_character(char *str, char t); +/** + * string_count_occurrences_single_character: + * + * Leaf function. + * + * Get the total number of occurrences of character @c in @str. + * + * @return Total number of occurrences of character @c + */ +int string_count_occurrences_single_character(const char *str, char c); -/* Replaces all spaces with the given character. */ -void string_replace_whitespace_with_single_character(char *str, char t); +/** + * string_replace_whitespace_with_single_character: + * + * Leaf function. + * + * Replaces all spaces with given character @c. + **/ +void string_replace_whitespace_with_single_character(char *str, char c); -/* Replaces multiple spaces with a single space in a string. */ +/** + * string_replace_multi_space_with_single_space: + * + * Leaf function. + * + * Replaces multiple spaces with a single space in a string. + **/ void string_replace_multi_space_with_single_space(char *str); -/* Remove all spaces from the given string. */ -void string_remove_all_whitespace(char* str_trimmed, const char* str_untrimmed); +/** + * string_remove_all_whitespace: + * + * Leaf function. + * + * Remove all spaces from the given string. + **/ +void string_remove_all_whitespace(char *str_trimmed, const char *str); /* Retrieve the last occurance of the given character in a string. */ -int string_index_last_occurance(char str[], char t); +int string_index_last_occurance(const char *str, char c); -/* Find the position of a substring in a string. */ -int string_find_index_substring_string(const char* str1, const char* str2); +/** + * string_find_index_substring_string: + * @str : input string (must be non-NULL, otherwise UB) + * @substr : substring to find in @str + * + * Hidden non-leaf function cost: + * - Calls strstr + * + * Find the position of substring @substr in string @str. + **/ +int string_find_index_substring_string(const char *str, const char *substr); + +/** + * string_copy_only_ascii: + * + * Leaf function. + * + * Strips non-ASCII characters from a string. + **/ +void string_copy_only_ascii(char *str_stripped, const char *str); + +extern const unsigned char lr_char_props[256]; RETRO_END_DECLS diff --git a/platform/libretro/libretro-common/include/time/rtime.h b/platform/libretro/libretro-common/include/time/rtime.h index 7629c1eab..8012b881c 100644 --- a/platform/libretro/libretro-common/include/time/rtime.h +++ b/platform/libretro/libretro-common/include/time/rtime.h @@ -34,13 +34,28 @@ RETRO_BEGIN_DECLS /* TODO/FIXME: Move all generic time handling functions * to this file */ -/* Must be called before using rtime_localtime() */ +/** + * Must be called before using \c rtime_localtime(). + * May be called multiple times without ill effects, + * but must only be called from the main thread. + */ void rtime_init(void); -/* Must be called upon program termination */ +/** + * Must be called upon program or core termination. + * May be called multiple times without ill effects, + * but must only be called from the main thread. + */ void rtime_deinit(void); -/* Thread-safe wrapper for localtime() */ +/** + * Thread-safe wrapper around standard \c localtime(), + * which by itself is not guaranteed to be thread-safe. + * @param timep Pointer to a time_t object to convert. + * @param result Pointer to a tm object to store the result in. + * @return \c result. + * @see https://en.cppreference.com/w/c/chrono/localtime + */ struct tm *rtime_localtime(const time_t *timep, struct tm *result); RETRO_END_DECLS diff --git a/platform/libretro/libretro-common/streams/file_stream.c b/platform/libretro/libretro-common/streams/file_stream.c index 2ac5dbb83..f6be82005 100644 --- a/platform/libretro/libretro-common/streams/file_stream.c +++ b/platform/libretro/libretro-common/streams/file_stream.c @@ -25,7 +25,6 @@ #include #include #include -#include #ifdef HAVE_CONFIG_H #include "config.h" @@ -46,7 +45,6 @@ struct RFILE { struct retro_vfs_file_handle *hfile; bool error_flag; - bool eof_flag; }; static retro_vfs_get_path_t filestream_get_path_cb = NULL; @@ -83,7 +81,7 @@ void filestream_vfs_init(const struct retro_vfs_interface_info* vfs_info) filestream_rename_cb = NULL; if ( - (vfs_info->required_interface_version < + (vfs_info->required_interface_version < FILESTREAM_REQUIRED_VFS_VERSION) || !vfs_iface) return; @@ -109,18 +107,14 @@ bool filestream_exists(const char *path) if (!path || !*path) return false; - - dummy = filestream_open( + if (!(dummy = filestream_open( path, RETRO_VFS_FILE_ACCESS_READ, - RETRO_VFS_FILE_ACCESS_HINT_NONE); - - if (!dummy) + RETRO_VFS_FILE_ACCESS_HINT_NONE))) return false; if (filestream_close(dummy) != 0) - if (dummy) - free(dummy); + free(dummy); dummy = NULL; return true; @@ -158,19 +152,13 @@ int64_t filestream_truncate(RFILE *stream, int64_t length) return output; } -/** - * filestream_open: - * @path : path to file - * @mode : file mode to use when opening (read/write) - * @hints : - * - * Opens a file for reading or writing, depending on the requested mode. - * Returns a pointer to an RFILE if opened successfully, otherwise NULL. - **/ RFILE* filestream_open(const char *path, unsigned mode, unsigned hints) { struct retro_vfs_file_handle *fp = NULL; - RFILE* output = NULL; + RFILE* output = (RFILE*)malloc(sizeof(RFILE)); + + if (!output) + return NULL; if (filestream_open_cb) fp = (struct retro_vfs_file_handle*) @@ -180,11 +168,12 @@ RFILE* filestream_open(const char *path, unsigned mode, unsigned hints) retro_vfs_file_open_impl(path, mode, hints); if (!fp) + { + free(output); return NULL; + } - output = (RFILE*)malloc(sizeof(RFILE)); output->error_flag = false; - output->eof_flag = false; output->hfile = fp; return output; } @@ -226,7 +215,7 @@ int filestream_vscanf(RFILE *stream, const char* format, va_list *args) char buf[4096]; char subfmt[64]; va_list args_copy; - const char * bufiter = buf; + const char *bufiter = buf; int ret = 0; int64_t startpos = filestream_tell(stream); int64_t maxlen = filestream_read(stream, buf, sizeof(buf)-1); @@ -276,9 +265,9 @@ int filestream_vscanf(RFILE *stream, const char* format, va_list *args) *subfmtiter++ = *format++; } else if ( - *format == 'j' || - *format == 'z' || - *format == 't' || + *format == 'j' || + *format == 'z' || + *format == 't' || *format == 'L') { *subfmtiter++ = *format++; @@ -337,7 +326,7 @@ int filestream_vscanf(RFILE *stream, const char* format, va_list *args) } va_end(args_copy); - filestream_seek(stream, startpos+(bufiter-buf), + filestream_seek(stream, startpos + (bufiter - buf), RETRO_VFS_SEEK_POSITION_START); return ret; @@ -367,14 +356,12 @@ int64_t filestream_seek(RFILE *stream, int64_t offset, int seek_position) if (output == VFS_ERROR_RETURN_VALUE) stream->error_flag = true; - stream->eof_flag = false; - return output; } int filestream_eof(RFILE *stream) { - return stream->eof_flag; + return filestream_tell(stream) == filestream_get_size(stream) ? EOF : 0; } int64_t filestream_tell(RFILE *stream) @@ -399,7 +386,6 @@ void filestream_rewind(RFILE *stream) return; filestream_seek(stream, 0L, RETRO_VFS_SEEK_POSITION_START); stream->error_flag = false; - stream->eof_flag = false; } int64_t filestream_read(RFILE *stream, void *s, int64_t len) @@ -414,8 +400,6 @@ int64_t filestream_read(RFILE *stream, void *s, int64_t len) if (output == VFS_ERROR_RETURN_VALUE) stream->error_flag = true; - if (output < len) - stream->eof_flag = true; return output; } @@ -482,8 +466,8 @@ int filestream_putc(RFILE *stream, int c) char c_char = (char)c; if (!stream) return EOF; - return filestream_write(stream, &c_char, 1) == 1 - ? (int)(unsigned char)c + return filestream_write(stream, &c_char, 1) == 1 + ? (int)(unsigned char)c : EOF; } @@ -513,9 +497,7 @@ int filestream_printf(RFILE *stream, const char* format, ...) int filestream_error(RFILE *stream) { - if (stream && stream->error_flag) - return 1; - return 0; + return (stream && stream->error_flag); } int filestream_close(RFILE *stream) @@ -535,17 +517,6 @@ int filestream_close(RFILE *stream) return output; } -/** - * filestream_read_file: - * @path : path to file. - * @buf : buffer to allocate and read the contents of the - * file into. Needs to be freed manually. - * @len : optional output integer containing bytes read. - * - * Read the contents of a file into @buf. - * - * Returns: non zero on success. - */ int64_t filestream_read_file(const char *path, void **buf, int64_t *len) { int64_t ret = 0; @@ -561,25 +532,20 @@ int64_t filestream_read_file(const char *path, void **buf, int64_t *len) return 0; } - content_buf_size = filestream_get_size(file); - - if (content_buf_size < 0) + if ((content_buf_size = filestream_get_size(file)) < 0) goto error; - content_buf = malloc((size_t)(content_buf_size + 1)); - - if (!content_buf) + if (!(content_buf = malloc((size_t)(content_buf_size + 1)))) goto error; if ((int64_t)(uint64_t)(content_buf_size + 1) != (content_buf_size + 1)) goto error; - ret = filestream_read(file, content_buf, (int64_t)content_buf_size); - if (ret < 0) + if ((ret = filestream_read(file, content_buf, (int64_t)content_buf_size)) < + 0) goto error; if (filestream_close(file) != 0) - if (file) - free(file); + free(file); *buf = content_buf; @@ -593,9 +559,8 @@ int64_t filestream_read_file(const char *path, void **buf, int64_t *len) return 1; error: - if (file) - if (filestream_close(file) != 0) - free(file); + if (filestream_close(file) != 0) + free(file); if (content_buf) free(content_buf); if (len) @@ -604,16 +569,6 @@ int64_t filestream_read_file(const char *path, void **buf, int64_t *len) return 0; } -/** - * filestream_write_file: - * @path : path to file. - * @data : contents to write to the file. - * @size : size of the contents. - * - * Writes data to a file. - * - * Returns: true (1) on success, false (0) otherwise. - */ bool filestream_write_file(const char *path, const void *data, int64_t size) { int64_t ret = 0; @@ -622,20 +577,13 @@ bool filestream_write_file(const char *path, const void *data, int64_t size) RETRO_VFS_FILE_ACCESS_HINT_NONE); if (!file) return false; - ret = filestream_write(file, data, size); if (filestream_close(file) != 0) - if (file) - free(file); - - if (ret != size) - return false; - - return true; + free(file); + return (ret == size); } -/* Returned pointer must be freed by the caller. */ -char* filestream_getline(RFILE *stream) +char *filestream_getline(RFILE *stream) { char *newline_tmp = NULL; size_t cur_size = 8; @@ -650,16 +598,15 @@ char* filestream_getline(RFILE *stream) return NULL; } - in = filestream_getc(stream); + in = filestream_getc(stream); while (in != EOF && in != '\n') { if (idx == cur_size) { cur_size *= 2; - newline_tmp = (char*)realloc(newline, cur_size + 1); - if (!newline_tmp) + if (!(newline_tmp = (char*)realloc(newline, cur_size + 1))) { free(newline); return NULL; diff --git a/platform/libretro/libretro-common/streams/trans_stream_zlib.c b/platform/libretro/libretro-common/streams/trans_stream_zlib.c index e5d1a4af7..03921e712 100644 --- a/platform/libretro/libretro-common/streams/trans_stream_zlib.c +++ b/platform/libretro/libretro-common/streams/trans_stream_zlib.c @@ -30,7 +30,8 @@ struct zlib_trans_stream { z_stream z; - int ex; /* window_bits or level */ + int window_bits; + int level; bool inited; }; @@ -41,7 +42,8 @@ static void *zlib_deflate_stream_new(void) if (!ret) return NULL; ret->inited = false; - ret->ex = 9; + ret->level = 9; + ret->window_bits = 15; ret->z.next_in = NULL; ret->z.avail_in = 0; @@ -70,7 +72,7 @@ static void *zlib_inflate_stream_new(void) if (!ret) return NULL; ret->inited = false; - ret->ex = MAX_WBITS; + ret->window_bits = MAX_WBITS; ret->z.next_in = NULL; ret->z.avail_in = 0; @@ -115,23 +117,29 @@ static void zlib_inflate_stream_free(void *data) static bool zlib_deflate_define(void *data, const char *prop, uint32_t val) { - struct zlib_trans_stream *z = (struct zlib_trans_stream *) data; + struct zlib_trans_stream *z = (struct zlib_trans_stream*)data; + if (!data) + return false; + if (string_is_equal(prop, "level")) - { - if (z) - z->ex = (int) val; - return true; - } - return false; + z->level = (int) val; + else if (string_is_equal(prop, "window_bits")) + z->window_bits = (int) val; + else + return false; + + return true; } static bool zlib_inflate_define(void *data, const char *prop, uint32_t val) { - struct zlib_trans_stream *z = (struct zlib_trans_stream *) data; + struct zlib_trans_stream *z = (struct zlib_trans_stream*)data; + if (!data) + return false; + if (string_is_equal(prop, "window_bits")) { - if (z) - z->ex = (int) val; + z->window_bits = (int) val; return true; } return false; @@ -149,7 +157,7 @@ static void zlib_deflate_set_in(void *data, const uint8_t *in, uint32_t in_size) if (!z->inited) { - deflateInit(&z->z, z->ex); + deflateInit2(&z->z, z->level, Z_DEFLATED , z->window_bits, 8, Z_DEFAULT_STRATEGY ); z->inited = true; } } @@ -165,7 +173,7 @@ static void zlib_inflate_set_in(void *data, const uint8_t *in, uint32_t in_size) z->z.avail_in = in_size; if (!z->inited) { - inflateInit2(&z->z, z->ex); + inflateInit2(&z->z, z->window_bits); z->inited = true; } } @@ -195,7 +203,7 @@ static bool zlib_deflate_trans( if (!zt->inited) { - deflateInit(z, zt->ex); + deflateInit2(z, zt->level, Z_DEFLATED , zt->window_bits, 8, Z_DEFAULT_STRATEGY ); zt->inited = true; } @@ -258,7 +266,7 @@ static bool zlib_inflate_trans( if (!zt->inited) { - inflateInit2(z, zt->ex); + inflateInit2(z, zt->window_bits); zt->inited = true; } diff --git a/platform/libretro/libretro-common/string/stdstring.c b/platform/libretro/libretro-common/string/stdstring.c index 45446ca77..7f508ad7e 100644 --- a/platform/libretro/libretro-common/string/stdstring.c +++ b/platform/libretro/libretro-common/string/stdstring.c @@ -24,6 +24,7 @@ #include #include +#include #include #include @@ -47,18 +48,6 @@ const uint8_t lr_char_props[256] = { 0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, /* Fx */ }; -char *string_init(const char *src) -{ - return src ? strdup(src) : NULL; -} - -void string_set(char **string, const char *src) -{ - free(*string); - *string = string_init(src); -} - - char *string_to_upper(char *s) { char *cs = (char *)s; @@ -89,9 +78,11 @@ char *string_ucwords(char *s) } char *string_replace_substring(const char *in, - const char *pattern, const char *replacement) + const char *pattern, size_t pattern_len, + const char *replacement, size_t replacement_len) { - size_t numhits, pattern_len, replacement_len, outlen; + size_t outlen; + size_t numhits = 0; const char *inat = NULL; const char *inprev = NULL; char *out = NULL; @@ -102,9 +93,6 @@ char *string_replace_substring(const char *in, if (!pattern || !replacement) return strdup(in); - pattern_len = strlen(pattern); - replacement_len = strlen(replacement); - numhits = 0; inat = in; while ((inat = strstr(inat, pattern))) @@ -114,9 +102,8 @@ char *string_replace_substring(const char *in, } outlen = strlen(in) - pattern_len*numhits + replacement_len*numhits; - out = (char *)malloc(outlen+1); - if (!out) + if (!(out = (char *)malloc(outlen+1))) return NULL; outat = out; @@ -129,7 +116,7 @@ char *string_replace_substring(const char *in, outat += inat-inprev; memcpy(outat, replacement, replacement_len); outat += replacement_len; - inat += pattern_len; + inat += pattern_len; inprev = inat; } strcpy(outat, inprev); @@ -137,7 +124,11 @@ char *string_replace_substring(const char *in, return out; } -/* Remove leading whitespaces */ +/** + * string_trim_whitespace_left: + * + * Remove leading whitespaces + **/ char *string_trim_whitespace_left(char *const s) { if (s && *s) @@ -158,7 +149,11 @@ char *string_trim_whitespace_left(char *const s) return s; } -/* Remove trailing whitespaces */ +/** + * string_trim_whitespace_right: + * + * Remove trailing whitespaces + **/ char *string_trim_whitespace_right(char *const s) { if (s && *s) @@ -178,7 +173,11 @@ char *string_trim_whitespace_right(char *const s) return s; } -/* Remove leading and trailing whitespaces */ +/** + * string_trim_whitespace: + * + * Remove leading and trailing whitespaces + **/ char *string_trim_whitespace(char *const s) { string_trim_whitespace_right(s); /* order matters */ @@ -187,49 +186,62 @@ char *string_trim_whitespace(char *const s) return s; } -void word_wrap(char *dst, size_t dst_size, const char *src, int line_width, int wideglyph_width, unsigned max_lines) +/** + * word_wrap: + * @dst : pointer to destination buffer. + * @dst_size : size of destination buffer. + * @src : pointer to input string. + * @line_width : max number of characters per line. + * @wideglyph_width : not used, but is necessary to keep + * compatibility with word_wrap_wideglyph(). + * @max_lines : max lines of destination string. + * 0 means no limit. + * + * Wraps string specified by 'src' to destination buffer + * specified by 'dst' and 'dst_size'. + * This function assumes that all glyphs in the string + * have an on-screen pixel width similar to that of + * regular Latin characters - i.e. it will not wrap + * correctly any text containing so-called 'wide' Unicode + * characters (e.g. CJK languages, emojis, etc.). + **/ +size_t word_wrap( + char *dst, size_t dst_size, + const char *src, size_t src_len, + int line_width, int wideglyph_width, unsigned max_lines) { - char *lastspace = NULL; + char *last_space = NULL; unsigned counter = 0; unsigned lines = 1; - size_t src_len = strlen(src); const char *src_end = src + src_len; /* Prevent buffer overflow */ if (dst_size < src_len + 1) - return; + return 0; /* Early return if src string length is less * than line width */ - if (src_len < line_width) - { - strcpy(dst, src); - return; - } + if (src_len < (size_t)line_width) + return strlcpy(dst, src, dst_size); while (*src != '\0') { - unsigned char_len; - - char_len = (unsigned)(utf8skip(src, 1) - src); + unsigned char_len = (unsigned)(utf8skip(src, 1) - src); counter++; if (*src == ' ') - lastspace = dst; /* Remember the location of the whitespace */ + last_space = dst; /* Remember the location of the whitespace */ else if (*src == '\n') { /* If newlines embedded in the input, * reset the index */ lines++; - counter = 0; + counter = 0; /* Early return if remaining src string * length is less than line width */ if (src_end - src <= line_width) - { - strcpy(dst, src); - return; - } + return strlcpy(dst, src, dst_size); } while (char_len--) @@ -239,36 +251,69 @@ void word_wrap(char *dst, size_t dst_size, const char *src, int line_width, int { counter = 0; - if (lastspace && (max_lines == 0 || lines < max_lines)) + if (last_space && (max_lines == 0 || lines < max_lines)) { /* Replace nearest (previous) whitespace * with newline character */ - *lastspace = '\n'; + *last_space = '\n'; lines++; - src -= dst - lastspace - 1; - dst = lastspace + 1; - lastspace = NULL; + src -= dst - last_space - 1; + dst = last_space + 1; + last_space = NULL; /* Early return if remaining src string * length is less than line width */ if (src_end - src < line_width) - { - strcpy(dst, src); - return; - } + return strlcpy(dst, src, dst_size); } } } *dst = '\0'; + return 0; } -void word_wrap_wideglyph(char *dst, size_t dst_size, const char *src, int line_width, int wideglyph_width, unsigned max_lines) +/** + * word_wrap_wideglyph: + * @dst : pointer to destination buffer. + * @dst_size : size of destination buffer. + * @src : pointer to input string. + * @line_width : max number of characters per line. + * @wideglyph_width : effective width of 'wide' Unicode glyphs. + * the value here is normalised relative to the + * typical on-screen pixel width of a regular + * Latin character: + * - a regular Latin character is defined to + * have an effective width of 100 + * - wideglyph_width = 100 * (wide_character_pixel_width / latin_character_pixel_width) + * - e.g. if 'wide' Unicode characters in 'src' + * have an on-screen pixel width twice that of + * regular Latin characters, wideglyph_width + * would be 200 + * @max_lines : max lines of destination string. + * 0 means no limit. + * + * Wraps string specified by @src to destination buffer + * specified by @dst and @dst_size. + * This function assumes that all glyphs in the string + * are: + * - EITHER 'non-wide' Unicode glyphs, with an on-screen + * pixel width similar to that of regular Latin characters + * - OR 'wide' Unicode glyphs (e.g. CJK languages, emojis, etc.) + * with an on-screen pixel width defined by @wideglyph_width + * Note that wrapping may occur in inappropriate locations + * if @src string contains 'wide' Unicode characters whose + * on-screen pixel width deviates greatly from the set + * @wideglyph_width value. + **/ +size_t word_wrap_wideglyph(char *dst, size_t dst_size, + const char *src, size_t src_len, int line_width, + int wideglyph_width, unsigned max_lines) { char *lastspace = NULL; char *lastwideglyph = NULL; - const char *src_end = src + strlen(src); + const char *src_end = src + src_len; unsigned lines = 1; /* 'line_width' means max numbers of characters per line, * but this metric is only meaningful when dealing with @@ -294,20 +339,15 @@ void word_wrap_wideglyph(char *dst, size_t dst_size, const char *src, int line_w unsigned counter_normalized = 0; int line_width_normalized = line_width * 100; int additional_counter_normalized = wideglyph_width - 100; - + /* Early return if src string length is less * than line width */ if (src_end - src < line_width) - { - strlcpy(dst, src, dst_size); - return; - } + return strlcpy(dst, src, dst_size); while (*src != '\0') { - unsigned char_len; - - char_len = (unsigned)(utf8skip(src, 1) - src); + unsigned char_len = (unsigned)(utf8skip(src, 1) - src); counter_normalized += 100; /* Prevent buffer overflow */ @@ -315,7 +355,7 @@ void word_wrap_wideglyph(char *dst, size_t dst_size, const char *src, int line_w break; if (*src == ' ') - lastspace = dst; /* Remember the location of the whitespace */ + lastspace = dst; /* Remember the location of the whitespace */ else if (*src == '\n') { /* If newlines embedded in the input, @@ -326,16 +366,13 @@ void word_wrap_wideglyph(char *dst, size_t dst_size, const char *src, int line_w /* Early return if remaining src string * length is less than line width */ if (src_end - src <= line_width) - { - strlcpy(dst, src, dst_size); - return; - } + return strlcpy(dst, src, dst_size); } else if (char_len >= 3) { /* Remember the location of the first byte * whose length as UTF-8 >= 3*/ - lastwideglyph = dst; + lastwideglyph = dst; counter_normalized += additional_counter_normalized; } @@ -354,17 +391,14 @@ void word_wrap_wideglyph(char *dst, size_t dst_size, const char *src, int line_w /* Insert newline character */ *lastwideglyph = '\n'; lines++; - src -= dst - lastwideglyph; - dst = lastwideglyph + 1; - lastwideglyph = NULL; + src -= dst - lastwideglyph; + dst = lastwideglyph + 1; + lastwideglyph = NULL; /* Early return if remaining src string * length is less than line width */ if (src_end - src <= line_width) - { - strlcpy(dst, src, dst_size); - return; - } + return strlcpy(dst, src, dst_size); } else if (lastspace) { @@ -372,28 +406,29 @@ void word_wrap_wideglyph(char *dst, size_t dst_size, const char *src, int line_w * with newline character */ *lastspace = '\n'; lines++; - src -= dst - lastspace - 1; - dst = lastspace + 1; - lastspace = NULL; + src -= dst - lastspace - 1; + dst = lastspace + 1; + lastspace = NULL; /* Early return if remaining src string * length is less than line width */ if (src_end - src < line_width) - { - strlcpy(dst, src, dst_size); - return; - } + return strlcpy(dst, src, dst_size); } } } *dst = '\0'; + return 0; } -/* Splits string into tokens seperated by 'delim' +/** + * string_tokenize: + * + * Splits string into tokens separated by @delim * > Returned token string must be free()'d * > Returns NULL if token is not found - * > After each call, 'str' is set to the position after the + * > After each call, @str is set to the position after the * last found token * > Tokens *include* empty strings * Usage example: @@ -406,7 +441,7 @@ void word_wrap_wideglyph(char *dst, size_t dst_size, const char *src, int line_w * free(token); * token = NULL; * } - */ + **/ char* string_tokenize(char **str, const char *delim) { /* Taken from https://codereview.stackexchange.com/questions/216956/strtok-function-thread-safe-supports-empty-tokens-doesnt-change-string# */ @@ -419,25 +454,20 @@ char* string_tokenize(char **str, const char *delim) if (!str || string_is_empty(delim)) return NULL; - str_ptr = *str; /* Note: we don't check string_is_empty() here, * empty strings are valid */ - if (!str_ptr) + if (!(str_ptr = *str)) return NULL; /* Search for delimiter */ - delim_ptr = strstr(str_ptr, delim); - - if (delim_ptr) + if ((delim_ptr = strstr(str_ptr, delim))) token_len = delim_ptr - str_ptr; else token_len = strlen(str_ptr); /* Allocate token string */ - token = (char *)malloc((token_len + 1) * sizeof(char)); - - if (!token) + if (!(token = (char *)malloc((token_len + 1) * sizeof(char)))) return NULL; /* Copy token */ @@ -450,42 +480,53 @@ char* string_tokenize(char **str, const char *delim) return token; } -/* Removes every instance of character 'c' from 'str' */ +/** + * string_remove_all_chars: + * @str : input string (must be non-NULL, otherwise UB) + * + * Leaf function. + * + * Removes every instance of character @c from @str + **/ void string_remove_all_chars(char *str, char c) { - char *read_ptr = NULL; - char *write_ptr = NULL; - - if (string_is_empty(str)) - return; - - read_ptr = str; - write_ptr = str; + char *read_ptr = str; + char *write_ptr = str; while (*read_ptr != '\0') { *write_ptr = *read_ptr++; - write_ptr += (*write_ptr != c) ? 1 : 0; + if (*write_ptr != c) + write_ptr++; } *write_ptr = '\0'; } -/* Replaces every instance of character 'find' in 'str' - * with character 'replace' */ +/** + * string_replace_all_chars: + * @str : input string (must be non-NULL, otherwise UB) + * @find : character to find + * @replace : character to replace @find with + * + * Replaces every instance of character @find in @str + * with character @replace + **/ void string_replace_all_chars(char *str, char find, char replace) { char *str_ptr = str; - - if (string_is_empty(str)) - return; - while ((str_ptr = strchr(str_ptr, find))) *str_ptr++ = replace; } -/* Converts string to unsigned integer. - * Returns 0 if string is invalid */ +/** + * string_to_unsigned: + * @str : input string + * + * Converts string to unsigned integer. + * + * @return 0 if string is invalid, otherwise > 0 + **/ unsigned string_to_unsigned(const char *str) { const char *ptr = NULL; @@ -502,27 +543,33 @@ unsigned string_to_unsigned(const char *str) return (unsigned)strtoul(str, NULL, 10); } -/* Converts hexadecimal string to unsigned integer. +/** + * string_hex_to_unsigned: + * @str : input string (must be non-NULL, otherwise UB) + * + * Converts hexadecimal string to unsigned integer. * Handles optional leading '0x'. - * Returns 0 if string is invalid */ + * + * @return 0 if string is invalid, otherwise > 0 + **/ unsigned string_hex_to_unsigned(const char *str) { const char *hex_str = str; const char *ptr = NULL; - size_t len; - - if (string_is_empty(str)) - return 0; /* Remove leading '0x', if required */ - len = strlen(str); - - if (len >= 2) - if ((str[0] == '0') && - ((str[1] == 'x') || (str[1] == 'X'))) + if (str[0] != '\0' && str[1] != '\0') + { + if ( (str[0] == '0') && + ((str[1] == 'x') || + (str[1] == 'X'))) + { hex_str = str + 2; - - if (string_is_empty(hex_str)) + if (string_is_empty(hex_str)) + return 0; + } + } + else return 0; /* Check for valid characters */ @@ -536,97 +583,115 @@ unsigned string_hex_to_unsigned(const char *str) } /** - * Get the total number of occurrences of a character in the given string. + * string_count_occurrences_single_character: + * + * Leaf function. + * + * Get the total number of occurrences of character @c in @str. + * + * @return Total number of occurrences of character @c */ -int string_count_occurrences_single_character(char *str, char t) +int string_count_occurrences_single_character(const char *str, char c) { - int ctr = 0; - int i; + int count = 0; - for (i = 0; str[i] != '\0'; ++i) { - if (t == str[i]) - ++ctr; - } + for (; *str; str++) + if (*str == c) + count++; - return ctr; + return count; } /** - * Replaces all spaces with the given character. - */ -void string_replace_whitespace_with_single_character(char *str, char t) + * string_replace_whitespace_with_single_character: + * + * Leaf function. + * + * Replaces all spaces with given character @c. + **/ +void string_replace_whitespace_with_single_character(char *str, char c) { - - while (*str) { - if (isspace(*str)) - *str = t; - str++; - } + for (; *str; str++) + if (ISSPACE(*str)) + *str = c; } /** + * string_replace_multi_space_with_single_space: + * + * Leaf function. + * * Replaces multiple spaces with a single space in a string. - */ + **/ void string_replace_multi_space_with_single_space(char *str) { - char *dest = str; + char *str_trimmed = str; + bool prev_is_space = false; + bool curr_is_space = false; - while (*str != '\0') + for (; *str; str++) { - while (*str == ' ' && *(str + 1) == ' ') - str++; - - *dest++ = *str++; + curr_is_space = ISSPACE(*str); + if (prev_is_space && curr_is_space) + continue; + *str_trimmed++ = *str; + prev_is_space = curr_is_space; } - - *dest = '\0'; + *str_trimmed = '\0'; } /** + * string_remove_all_whitespace: + * + * Leaf function. + * * Remove all spaces from the given string. - */ -void string_remove_all_whitespace(char* str_trimmed, const char* str_untrimmed) + **/ +void string_remove_all_whitespace(char *str_trimmed, const char *str) { - while (*str_untrimmed != '\0') - { - if(!isspace(*str_untrimmed)) - { - *str_trimmed = *str_untrimmed; - str_trimmed++; - } - str_untrimmed++; - } + for (; *str; str++) + if (!ISSPACE(*str)) + *str_trimmed++ = *str; *str_trimmed = '\0'; } /** * Retrieve the last occurance of the given character in a string. */ -int string_index_last_occurance(char *str, char t) +int string_index_last_occurance(const char *str, char c) { - const char * ret = strrchr(str, t); - if (ret) - return ret-str; - + const char *pos = strrchr(str, c); + if (pos) + return (int)(pos - str); return -1; } /** - * Find the position of a substring in a string. - */ -int string_find_index_substring_string(const char* str1, const char* str2) + * string_find_index_substring_string: + * @str : input string (must be non-NULL, otherwise UB) + * @substr : substring to find in @str + * + * Find the position of substring @substr in string @str. + **/ +int string_find_index_substring_string(const char *str, const char *substr) { - int index; - - if (str1[0] != '\0') - { - const char *pfound = strstr(str1, str2); - if (pfound != NULL) - { - index = (pfound - str1); - return index; - } - } - + const char *pos = strstr(str, substr); + if (pos) + return (int)(pos - str); return -1; } + +/** + * string_copy_only_ascii: + * + * Leaf function. + * + * Strips non-ASCII characters from a string. + **/ +void string_copy_only_ascii(char *str_stripped, const char *str) +{ + for (; *str; str++) + if (*str > 0x1F && *str < 0x7F) + *str_stripped++ = *str; + *str_stripped = '\0'; +} diff --git a/platform/libretro/libretro-common/time/rtime.c b/platform/libretro/libretro-common/time/rtime.c index d66c228fb..fee0dabcb 100644 --- a/platform/libretro/libretro-common/time/rtime.c +++ b/platform/libretro/libretro-common/time/rtime.c @@ -22,7 +22,6 @@ #ifdef HAVE_THREADS #include -#include #include #endif @@ -41,8 +40,6 @@ void rtime_init(void) #ifdef HAVE_THREADS if (!rtime_localtime_lock) rtime_localtime_lock = slock_new(); - - retro_assert(rtime_localtime_lock); #endif } diff --git a/platform/libretro/libretro-common/vfs/vfs_implementation.c b/platform/libretro/libretro-common/vfs/vfs_implementation.c index afd4f0f63..e98a27db6 100644 --- a/platform/libretro/libretro-common/vfs/vfs_implementation.c +++ b/platform/libretro/libretro-common/vfs/vfs_implementation.c @@ -26,7 +26,7 @@ #include #include -#include +#include /* string_is_empty */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -57,11 +57,6 @@ # include # endif # include -# if defined(ORBIS) -# include -# include -# include -# endif # if defined(WIIU) # include # endif @@ -74,11 +69,6 @@ # include # include # include -#elif defined(ORBIS) -# include -# include -# include -# include #elif !defined(_WIN32) # if defined(PSP) # include @@ -124,19 +114,66 @@ #include #endif -#if defined(ORBIS) -#include -#include -#include -#endif + #if defined(PSP) #include #endif #if defined(__PS3__) || defined(__PSL1GHT__) -#include -#if defined(__PSL1GHT__) +#define FS_SUCCEEDED 0 +#define FS_TYPE_DIR 1 +#ifdef __PSL1GHT__ #include +#ifndef O_RDONLY +#define O_RDONLY SYS_O_RDONLY +#endif +#ifndef O_WRONLY +#define O_WRONLY SYS_O_WRONLY +#endif +#ifndef O_CREAT +#define O_CREAT SYS_O_CREAT +#endif +#ifndef O_TRUNC +#define O_TRUNC SYS_O_TRUNC +#endif +#ifndef O_RDWR +#define O_RDWR SYS_O_RDWR +#endif +#else +#include +#ifndef O_RDONLY +#define O_RDONLY CELL_FS_O_RDONLY +#endif +#ifndef O_WRONLY +#define O_WRONLY CELL_FS_O_WRONLY +#endif +#ifndef O_CREAT +#define O_CREAT CELL_FS_O_CREAT +#endif +#ifndef O_TRUNC +#define O_TRUNC CELL_FS_O_TRUNC +#endif +#ifndef O_RDWR +#define O_RDWR CELL_FS_O_RDWR +#endif +#ifndef sysFsStat +#define sysFsStat cellFsStat +#endif +#ifndef sysFSDirent +#define sysFSDirent CellFsDirent +#endif +#ifndef sysFsOpendir +#define sysFsOpendir cellFsOpendir +#endif +#ifndef sysFsReaddir +#define sysFsReaddir cellFsReaddir +#endif +#ifndef sysFSDirent +#define sysFSDirent CellFsDirent +#endif +#ifndef sysFsClosedir +#define sysFsClosedir cellFsClosedir +#endif #endif #endif @@ -200,13 +237,6 @@ int64_t retro_vfs_file_seek_internal( #ifdef ATLEAST_VC2005 /* VC2005 and up have a special 64-bit fseek */ return _fseeki64(stream->fp, offset, whence); -#elif defined(ORBIS) - { - int ret = orbisLseek(stream->fd, offset, whence); - if (ret < 0) - return -1; - return 0; - } #elif defined(HAVE_64BIT_OFFSETS) return fseeko(stream->fp, (off_t)offset, whence); #else @@ -269,22 +299,9 @@ int64_t retro_vfs_file_seek_internal( libretro_vfs_implementation_file *retro_vfs_file_open_impl( const char *path, unsigned mode, unsigned hints) { -#if defined(VFS_FRONTEND) || defined(HAVE_CDROM) - int path_len = (int)strlen(path); -#endif -#ifdef VFS_FRONTEND - const char *dumb_prefix = "vfsonly://"; - size_t dumb_prefix_siz = STRLEN_CONST("vfsonly://"); - int dumb_prefix_len = (int)dumb_prefix_siz; -#endif -#ifdef HAVE_CDROM - const char *cdrom_prefix = "cdrom://"; - size_t cdrom_prefix_siz = STRLEN_CONST("cdrom://"); - int cdrom_prefix_len = (int)cdrom_prefix_siz; -#endif int flags = 0; const char *mode_str = NULL; - libretro_vfs_implementation_file *stream = + libretro_vfs_implementation_file *stream = (libretro_vfs_implementation_file*) malloc(sizeof(*stream)); @@ -306,9 +323,18 @@ libretro_vfs_implementation_file *retro_vfs_file_open_impl( stream->scheme = VFS_SCHEME_NONE; #ifdef VFS_FRONTEND - if (path_len >= dumb_prefix_len) - if (!memcmp(path, dumb_prefix, dumb_prefix_len)) - path += dumb_prefix_siz; + if ( path + && path[0] == 'v' + && path[1] == 'f' + && path[2] == 's' + && path[3] == 'o' + && path[4] == 'n' + && path[5] == 'l' + && path[6] == 'y' + && path[7] == ':' + && path[8] == '/' + && path[9] == '/') + path += sizeof("vfsonly://")-1; #endif #ifdef HAVE_CDROM @@ -325,13 +351,19 @@ libretro_vfs_implementation_file *retro_vfs_file_open_impl( stream->cdrom.last_frame[0] = '\0'; stream->cdrom.last_frame_valid = false; - if (path_len > cdrom_prefix_len) + if ( path + && path[0] == 'c' + && path[1] == 'd' + && path[2] == 'r' + && path[3] == 'o' + && path[4] == 'm' + && path[5] == ':' + && path[6] == '/' + && path[7] == '/' + && path[8] != '\0') { - if (!memcmp(path, cdrom_prefix, cdrom_prefix_len)) - { - path += cdrom_prefix_siz; - stream->scheme = VFS_SCHEME_CDROM; - } + path += sizeof("cdrom://")-1; + stream->scheme = VFS_SCHEME_CDROM; } #endif @@ -359,24 +391,20 @@ libretro_vfs_implementation_file *retro_vfs_file_open_impl( mode_str = "wb"; flags = O_WRONLY | O_CREAT | O_TRUNC; -#if !defined(ORBIS) #if !defined(_WIN32) flags |= S_IRUSR | S_IWUSR; #else flags |= O_BINARY; -#endif #endif break; case RETRO_VFS_FILE_ACCESS_READ_WRITE: mode_str = "w+b"; flags = O_RDWR | O_CREAT | O_TRUNC; -#if !defined(ORBIS) #if !defined(_WIN32) flags |= S_IRUSR | S_IWUSR; #else flags |= O_BINARY; -#endif #endif break; @@ -385,12 +413,10 @@ libretro_vfs_implementation_file *retro_vfs_file_open_impl( mode_str = "r+b"; flags = O_RDWR; -#if !defined(ORBIS) #if !defined(_WIN32) flags |= S_IRUSR | S_IWUSR; #else flags |= O_BINARY; -#endif #endif break; @@ -400,15 +426,6 @@ libretro_vfs_implementation_file *retro_vfs_file_open_impl( if ((stream->hints & RFILE_HINT_UNBUFFERED) == 0) { -#ifdef ORBIS - int fd = orbisOpen(path, flags, 0644); - if (fd < 0) - { - stream->fd = -1; - goto error; - } - stream->fd = fd; -#else FILE *fp; #ifdef HAVE_CDROM if (stream->scheme == VFS_SCHEME_CDROM) @@ -425,25 +442,24 @@ libretro_vfs_implementation_file *retro_vfs_file_open_impl( else #endif { - fp = (FILE*)fopen_utf8(path, mode_str); - - if (!fp) + if (!(fp = (FILE*)fopen_utf8(path, mode_str))) goto error; stream->fp = fp; } + /* Regarding setvbuf: * * https://www.freebsd.org/cgi/man.cgi?query=setvbuf&apropos=0&sektion=0&manpath=FreeBSD+11.1-RELEASE&arch=default&format=html * - * If the size argument is not zero but buf is NULL, + * If the size argument is not zero but buf is NULL, * a buffer of the given size will be allocated immediately, and * released on close. This is an extension to ANSI C. * - * Since C89 does not support specifying a NULL buffer + * Since C89 does not support specifying a NULL buffer * with a non-zero size, we create and track our own buffer for it. */ - /* TODO: this is only useful for a few platforms, + /* TODO: this is only useful for a few platforms, * find which and add ifdef */ #if defined(_3DS) if (stream->scheme != VFS_SCHEME_CDROM) @@ -455,18 +471,14 @@ libretro_vfs_implementation_file *retro_vfs_file_open_impl( #elif defined(WIIU) if (stream->scheme != VFS_SCHEME_CDROM) { - const int bufsize = 128*1024; + const int bufsize = 128 * 1024; stream->buf = (char*)memalign(0x40, bufsize); if (stream->fp) setvbuf(stream->fp, stream->buf, _IOFBF, bufsize); - } - if (stream->scheme != VFS_SCHEME_CDROM) - { stream->buf = (char*)calloc(1, 0x4000); if (stream->fp) setvbuf(stream->fp, stream->buf, _IOFBF, 0x4000); } -#endif #endif } else @@ -502,18 +514,12 @@ libretro_vfs_implementation_file *retro_vfs_file_open_impl( retro_vfs_file_seek_internal(stream, 0, SEEK_SET); - stream->mapped = (uint8_t*)mmap((void*)0, - stream->mapsize, PROT_READ, MAP_SHARED, stream->fd, 0); - - if (stream->mapped == MAP_FAILED) + if ((stream->mapped = (uint8_t*)mmap((void*)0, + stream->mapsize, PROT_READ, MAP_SHARED, stream->fd, 0)) == MAP_FAILED) stream->hints &= ~RETRO_VFS_FILE_ACCESS_HINT_FREQUENT_ACCESS; } #endif } -#ifdef ORBIS - stream->size = orbisLseek(stream->fd, 0, SEEK_END); - orbisLseek(stream->fd, 0, SEEK_SET); -#else #ifdef HAVE_CDROM if (stream->scheme == VFS_SCHEME_CDROM) { @@ -534,7 +540,6 @@ libretro_vfs_implementation_file *retro_vfs_file_open_impl( retro_vfs_file_seek_internal(stream, 0, SEEK_SET); } -#endif return stream; error: @@ -569,14 +574,7 @@ int retro_vfs_file_close_impl(libretro_vfs_implementation_file *stream) } if (stream->fd > 0) - { -#ifdef ORBIS - orbisClose(stream->fd); - stream->fd = -1; -#else close(stream->fd); -#endif - } #ifdef HAVE_CDROM end: if (stream->cdrom.cue_buf) @@ -599,12 +597,7 @@ int retro_vfs_file_error_impl(libretro_vfs_implementation_file *stream) if (stream->scheme == VFS_SCHEME_CDROM) return retro_vfs_file_error_cdrom(stream); #endif -#ifdef ORBIS - /* TODO/FIXME - implement this? */ - return 0; -#else return ferror(stream->fp); -#endif } int64_t retro_vfs_file_size_impl(libretro_vfs_implementation_file *stream) @@ -616,18 +609,20 @@ int64_t retro_vfs_file_size_impl(libretro_vfs_implementation_file *stream) int64_t retro_vfs_file_truncate_impl(libretro_vfs_implementation_file *stream, int64_t length) { - if (!stream) - return -1; - #ifdef _WIN32 - if (_chsize(_fileno(stream->fp), length) != 0) - return -1; + if (stream && _chsize(_fileno(stream->fp), length) == 0) + { + stream->size = length; + return 0; + } #elif !defined(VITA) && !defined(PSP) && !defined(PS2) && !defined(ORBIS) && (!defined(SWITCH) || defined(HAVE_LIBNX)) - if (ftruncate(fileno(stream->fp), (off_t)length) != 0) - return -1; + if (stream && ftruncate(fileno(stream->fp), (off_t)length) == 0) + { + stream->size = length; + return 0; + } #endif - - return 0; + return -1; } int64_t retro_vfs_file_tell_impl(libretro_vfs_implementation_file *stream) @@ -641,14 +636,6 @@ int64_t retro_vfs_file_tell_impl(libretro_vfs_implementation_file *stream) if (stream->scheme == VFS_SCHEME_CDROM) return retro_vfs_file_tell_cdrom(stream); #endif -#ifdef ORBIS - { - int64_t ret = orbisLseek(stream->fd, 0, SEEK_CUR); - if (ret < 0) - return -1; - return ret; - } -#else #ifdef ATLEAST_VC2005 /* VC2005 and up have a special 64-bit ftell */ return _ftelli64(stream->fp); @@ -656,13 +643,12 @@ int64_t retro_vfs_file_tell_impl(libretro_vfs_implementation_file *stream) return ftello(stream->fp); #else return ftell(stream->fp); -#endif #endif } #ifdef HAVE_MMAP /* Need to check stream->mapped because this function * is called in filestream_open() */ - if (stream->mapped && stream->hints & + if (stream->mapped && stream->hints & RETRO_VFS_FILE_ACCESS_HINT_FREQUENT_ACCESS) return stream->mappos; #endif @@ -675,21 +661,7 @@ int64_t retro_vfs_file_tell_impl(libretro_vfs_implementation_file *stream) int64_t retro_vfs_file_seek_impl(libretro_vfs_implementation_file *stream, int64_t offset, int seek_position) { - int whence = -1; - switch (seek_position) - { - case RETRO_VFS_SEEK_POSITION_START: - whence = SEEK_SET; - break; - case RETRO_VFS_SEEK_POSITION_CURRENT: - whence = SEEK_CUR; - break; - case RETRO_VFS_SEEK_POSITION_END: - whence = SEEK_END; - break; - } - - return retro_vfs_file_seek_internal(stream, offset, whence); + return retro_vfs_file_seek_internal(stream, offset, seek_position); } int64_t retro_vfs_file_read_impl(libretro_vfs_implementation_file *stream, @@ -704,13 +676,7 @@ int64_t retro_vfs_file_read_impl(libretro_vfs_implementation_file *stream, if (stream->scheme == VFS_SCHEME_CDROM) return retro_vfs_file_read_cdrom(stream, s, len); #endif -#ifdef ORBIS - if (orbisRead(stream->fd, s, (size_t)len) < 0) - return -1; - return 0; -#else return fread(s, 1, (size_t)len, stream->fp); -#endif } #ifdef HAVE_MMAP if (stream->hints & RETRO_VFS_FILE_ACCESS_HINT_FREQUENT_ACCESS) @@ -733,83 +699,80 @@ int64_t retro_vfs_file_read_impl(libretro_vfs_implementation_file *stream, int64_t retro_vfs_file_write_impl(libretro_vfs_implementation_file *stream, const void *s, uint64_t len) { + int64_t pos = 0; + ssize_t result = -1; + if (!stream) return -1; if ((stream->hints & RFILE_HINT_UNBUFFERED) == 0) { -#ifdef ORBIS - if (orbisWrite(stream->fd, s, (size_t)len) < 0) - return -1; - return 0; -#else - return fwrite(s, 1, (size_t)len, stream->fp); -#endif - } + pos = retro_vfs_file_tell_impl(stream); + result = fwrite(s, 1, (size_t)len, stream->fp); + + if (result != -1 && pos + result > stream->size) + stream->size = pos + result; + return result; + } #ifdef HAVE_MMAP if (stream->hints & RETRO_VFS_FILE_ACCESS_HINT_FREQUENT_ACCESS) return -1; #endif - return write(stream->fd, s, (size_t)len); + + pos = retro_vfs_file_tell_impl(stream); + result = write(stream->fd, s, (size_t)len); + + if (result != -1 && pos + result > stream->size) + stream->size = pos + result; + + return result; } int retro_vfs_file_flush_impl(libretro_vfs_implementation_file *stream) { - if (!stream) - return -1; -#ifdef ORBIS - return 0; -#else - return fflush(stream->fp) == 0 ? 0 : -1; -#endif + if (stream && fflush(stream->fp) == 0) + return 0; + return -1; } int retro_vfs_file_remove_impl(const char *path) { + if (path && *path) + { + int ret = -1; #if defined(_WIN32) && !defined(_XBOX) - /* Win32 (no Xbox) */ - + /* Win32 (no Xbox) */ #if defined(_WIN32_WINNT) && _WIN32_WINNT < 0x0500 - char *path_local = NULL; + char *path_local = NULL; + if ((path_local = utf8_to_local_string_alloc(path))) + { + /* We need to check if path is a directory */ + if ((retro_vfs_stat_impl(path, NULL) & RETRO_VFS_STAT_IS_DIRECTORY) != 0) + ret = _rmdir(path_local); + else + ret = remove(path_local); + free(path_local); + } #else - wchar_t *path_wide = NULL; + wchar_t *path_wide = NULL; + if ((path_wide = utf8_to_utf16_string_alloc(path))) + { + /* We need to check if path is a directory */ + if ((retro_vfs_stat_impl(path, NULL) & RETRO_VFS_STAT_IS_DIRECTORY) != 0) + ret = _wrmdir(path_wide); + else + ret = _wremove(path_wide); + free(path_wide); + } #endif - if (!path || !*path) - return -1; -#if defined(_WIN32_WINNT) && _WIN32_WINNT < 0x0500 - path_local = utf8_to_local_string_alloc(path); - - if (path_local) - { - int ret = remove(path_local); - free(path_local); - - if (ret == 0) - return 0; - } #else - path_wide = utf8_to_utf16_string_alloc(path); - - if (path_wide) - { - int ret = _wremove(path_wide); - free(path_wide); - + ret = remove(path); +#endif if (ret == 0) return 0; } -#endif return -1; -#elif defined(ORBIS) - /* Orbis - * TODO/FIXME - stub for now */ - return 0; -#else - if (remove(path) == 0) - return 0; - return -1; -#endif } int retro_vfs_file_rename_impl(const char *old_path, const char *new_path) @@ -861,13 +824,6 @@ int retro_vfs_file_rename_impl(const char *old_path, const char *new_path) #endif return ret; -#elif defined(ORBIS) - /* Orbis */ - /* TODO/FIXME - Stub for now */ - if (!old_path || !*old_path || !new_path || !*new_path) - return -1; - return 0; - #else /* Every other platform */ if (!old_path || !*old_path || !new_path || !*new_path) @@ -887,154 +843,123 @@ const char *retro_vfs_file_get_path_impl( int retro_vfs_stat_impl(const char *path, int32_t *size) { - bool is_dir = false; - bool is_character_special = false; -#if defined(VITA) - /* Vita / PSP */ - SceIoStat buf; - int dir_ret; - char *tmp = NULL; - size_t len = 0; + int ret = RETRO_VFS_STAT_IS_VALID; if (!path || !*path) return 0; + { +#if defined(VITA) + /* Vita / PSP */ + SceIoStat stat_buf; + int dir_ret; + char *tmp = strdup(path); + size_t len = strlen(tmp); + if (tmp[len-1] == '/') + tmp[len-1] = '\0'; + + dir_ret = sceIoGetstat(tmp, &stat_buf); + free(tmp); + if (dir_ret < 0) + return 0; - tmp = strdup(path); - len = strlen(tmp); - if (tmp[len-1] == '/') - tmp[len-1] = '\0'; - - dir_ret = sceIoGetstat(tmp, &buf); - free(tmp); - if (dir_ret < 0) - return 0; - - if (size) - *size = (int32_t)buf.st_size; - - is_dir = FIO_S_ISDIR(buf.st_mode); -#elif defined(ORBIS) - /* Orbis */ - int dir_ret = 0; - - if (!path || !*path) - return 0; - - if (size) - *size = (int32_t)buf.st_size; - - dir_ret = orbisDopen(path); - is_dir = dir_ret > 0; - orbisDclose(dir_ret); + if (size) + *size = (int32_t)stat_buf.st_size; - is_character_special = S_ISCHR(buf.st_mode); + if (FIO_S_ISDIR(stat_buf.st_mode)) + ret |= RETRO_VFS_STAT_IS_DIRECTORY; #elif defined(__PSL1GHT__) || defined(__PS3__) - /* Lowlevel Lv2 */ - sysFSStat buf; + /* Lowlevel Lv2 */ + sysFSStat stat_buf; - if (!path || !*path) - return 0; - if (sysFsStat(path, &buf) < 0) - return 0; + if (sysFsStat(path, &stat_buf) < 0) + return 0; - if (size) - *size = (int32_t)buf.st_size; + if (size) + *size = (int32_t)stat_buf.st_size; - is_dir = ((buf.st_mode & S_IFMT) == S_IFDIR); + if ((stat_buf.st_mode & S_IFMT) == S_IFDIR) + ret |= RETRO_VFS_STAT_IS_DIRECTORY; #elif defined(_WIN32) - /* Windows */ - DWORD file_info; - struct _stat buf; + /* Windows */ + struct _stat stat_buf; #if defined(LEGACY_WIN32) - char *path_local = NULL; -#else - wchar_t *path_wide = NULL; -#endif + char *path_local = utf8_to_local_string_alloc(path); + DWORD file_info = GetFileAttributes(path_local); - if (!path || !*path) - return 0; + if (!string_is_empty(path_local)) + _stat(path_local, &stat_buf); -#if defined(LEGACY_WIN32) - path_local = utf8_to_local_string_alloc(path); - file_info = GetFileAttributes(path_local); - - if (!string_is_empty(path_local)) - _stat(path_local, &buf); - - if (path_local) - free(path_local); + if (path_local) + free(path_local); #else - path_wide = utf8_to_utf16_string_alloc(path); - file_info = GetFileAttributesW(path_wide); + wchar_t *path_wide = utf8_to_utf16_string_alloc(path); + DWORD file_info = GetFileAttributesW(path_wide); - _wstat(path_wide, &buf); + _wstat(path_wide, &stat_buf); - if (path_wide) - free(path_wide); + if (path_wide) + free(path_wide); #endif + if (file_info == INVALID_FILE_ATTRIBUTES) + return 0; - if (file_info == INVALID_FILE_ATTRIBUTES) - return 0; - - if (size) - *size = (int32_t)buf.st_size; - - is_dir = (file_info & FILE_ATTRIBUTE_DIRECTORY); + if (size) + *size = (int32_t)stat_buf.st_size; + if (file_info & FILE_ATTRIBUTE_DIRECTORY) + ret |= RETRO_VFS_STAT_IS_DIRECTORY; #elif defined(GEKKO) - /* On GEKKO platforms, paths cannot have - * trailing slashes - we must therefore - * remove them */ - char *path_buf = NULL; - int stat_ret = -1; - struct stat stat_buf; - size_t len; - - if (string_is_empty(path)) - return 0; - - path_buf = strdup(path); - if (!path_buf) - return 0; - - len = strlen(path_buf); - if (len > 0) - if (path_buf[len - 1] == '/') - path_buf[len - 1] = '\0'; - - stat_ret = stat(path_buf, &stat_buf); - free(path_buf); + /* On GEKKO platforms, paths cannot have + * trailing slashes - we must therefore + * remove them */ + size_t len; + char *path_buf = NULL; + struct stat stat_buf; + + if (!(path_buf = strdup(path))) + return 0; - if (stat_ret < 0) - return 0; + if ((len = strlen(path_buf)) > 0) + if (path_buf[len - 1] == '/') + path_buf[len - 1] = '\0'; - if (size) - *size = (int32_t)stat_buf.st_size; + if (stat(path_buf, &stat_buf) < 0) + { + free(path_buf); + return 0; + } - is_dir = S_ISDIR(stat_buf.st_mode); - is_character_special = S_ISCHR(stat_buf.st_mode); + free(path_buf); + + if (size) + *size = (int32_t)stat_buf.st_size; + if (S_ISDIR(stat_buf.st_mode)) + ret |= RETRO_VFS_STAT_IS_DIRECTORY; + if (S_ISCHR(stat_buf.st_mode)) + ret |= RETRO_VFS_STAT_IS_CHARACTER_SPECIAL; #else - /* Every other platform */ - struct stat buf; + /* Every other platform */ + struct stat stat_buf; - if (!path || !*path) - return 0; - if (stat(path, &buf) < 0) - return 0; + if (stat(path, &stat_buf) < 0) + return 0; - if (size) - *size = (int32_t)buf.st_size; + if (size) + *size = (int32_t)stat_buf.st_size; - is_dir = S_ISDIR(buf.st_mode); - is_character_special = S_ISCHR(buf.st_mode); + if (S_ISDIR(stat_buf.st_mode)) + ret |= RETRO_VFS_STAT_IS_DIRECTORY; + if (S_ISCHR(stat_buf.st_mode)) + ret |= RETRO_VFS_STAT_IS_CHARACTER_SPECIAL; #endif - return RETRO_VFS_STAT_IS_VALID | (is_dir ? RETRO_VFS_STAT_IS_DIRECTORY : 0) | (is_character_special ? RETRO_VFS_STAT_IS_CHARACTER_SPECIAL : 0); + } + return ret; } #if defined(VITA) #define path_mkdir_error(ret) (((ret) == SCE_ERROR_ERRNO_EEXIST)) -#elif defined(PSP) || defined(PS2) || defined(_3DS) || defined(WIIU) || defined(SWITCH) || defined(ORBIS) +#elif defined(PSP) || defined(PS2) || defined(_3DS) || defined(WIIU) || defined(SWITCH) #define path_mkdir_error(ret) ((ret) == -1) #else #define path_mkdir_error(ret) ((ret) < 0 && errno == EEXIST) @@ -1059,11 +984,9 @@ int retro_vfs_mkdir_impl(const char *dir) int ret = mkdir(dir, 0755); #elif defined(VITA) int ret = sceIoMkdir(dir, 0777); -#elif defined(ORBIS) - int ret = orbisMkdir(dir, 0755); #elif defined(__QNX__) int ret = mkdir(dir, 0777); -#elif defined(GEKKO) +#elif defined(GEKKO) || defined(WIIU) /* On GEKKO platforms, mkdir() fails if * the path has a trailing slash. We must * therefore remove it. */ @@ -1117,9 +1040,6 @@ struct libretro_vfs_implementation_dir int error; int directory; sysFSDirent entry; -#elif defined(ORBIS) - int directory; - struct dirent entry; #else DIR *directory; const struct dirent *entry; @@ -1143,7 +1063,6 @@ libretro_vfs_implementation_dir *retro_vfs_opendir_impl( const char *name, bool include_hidden) { #if defined(_WIN32) - unsigned path_len; char path_buf[1024]; size_t copied = 0; #if defined(LEGACY_WIN32) @@ -1154,28 +1073,25 @@ libretro_vfs_implementation_dir *retro_vfs_opendir_impl( #endif libretro_vfs_implementation_dir *rdir; - /*Reject null or empty string paths*/ + /* Reject NULL or empty string paths*/ if (!name || (*name == 0)) return NULL; /*Allocate RDIR struct. Tidied later with retro_closedir*/ - rdir = (libretro_vfs_implementation_dir*)calloc(1, sizeof(*rdir)); - if (!rdir) + if (!(rdir = (libretro_vfs_implementation_dir*) + calloc(1, sizeof(*rdir)))) return NULL; rdir->orig_path = strdup(name); #if defined(_WIN32) - path_buf[0] = '\0'; - path_len = strlen(name); - copied = strlcpy(path_buf, name, sizeof(path_buf)); /* Non-NT platforms don't like extra slashes in the path */ - if (name[path_len - 1] != '\\') - path_buf[copied++] = '\\'; + if (path_buf[copied - 1] != '\\') + path_buf [copied++] = '\\'; - path_buf[copied] = '*'; + path_buf[copied ] = '*'; path_buf[copied+1] = '\0'; #if defined(LEGACY_WIN32) @@ -1199,8 +1115,6 @@ libretro_vfs_implementation_dir *retro_vfs_opendir_impl( rdir->entry = NULL; #elif defined(__PSL1GHT__) || defined(__PS3__) rdir->error = sysFsOpendir(name, &rdir->directory); -#elif defined(ORBIS) - rdir->directory = orbisDopen(name); #else rdir->directory = opendir(name); rdir->entry = NULL; @@ -1211,6 +1125,8 @@ libretro_vfs_implementation_dir *retro_vfs_opendir_impl( rdir->entry.dwFileAttributes |= FILE_ATTRIBUTE_HIDDEN; else rdir->entry.dwFileAttributes &= ~FILE_ATTRIBUTE_HIDDEN; +#else + (void)include_hidden; #endif if (rdir->directory && !dirent_check_error(rdir)) @@ -1238,8 +1154,6 @@ bool retro_vfs_readdir_impl(libretro_vfs_implementation_dir *rdir) uint64_t nread; rdir->error = sysFsReaddir(rdir->directory, &rdir->entry, &nread); return (nread != 0); -#elif defined(ORBIS) - return (orbisDread(rdir->directory, &rdir->entry) > 0); #else return ((rdir->entry = readdir(rdir->directory)) != NULL); #endif @@ -1258,7 +1172,7 @@ const char *retro_vfs_dirent_get_name_impl(libretro_vfs_implementation_dir *rdir if (name) free(name); return (char*)rdir->entry.cFileName; -#elif defined(VITA) || defined(ORBIS) || defined(__PSL1GHT__) || defined(__PS3__) +#elif defined(VITA) || defined(__PSL1GHT__) || defined(__PS3__) return rdir->entry.d_name; #else if (!rdir || !rdir->entry) @@ -1278,12 +1192,6 @@ bool retro_vfs_dirent_is_dir_impl(libretro_vfs_implementation_dir *rdir) #elif defined(__PSL1GHT__) || defined(__PS3__) sysFSDirent *entry = (sysFSDirent*)&rdir->entry; return (entry->d_type == FS_TYPE_DIR); -#elif defined(ORBIS) - const struct dirent *entry = &rdir->entry; - if (entry->d_type == DT_DIR) - return true; - if (!(entry->d_type == DT_UNKNOWN || entry->d_type == DT_LNK)) - return false; #else struct stat buf; char path[PATH_MAX_LENGTH]; @@ -1296,8 +1204,7 @@ bool retro_vfs_dirent_is_dir_impl(libretro_vfs_implementation_dir *rdir) return false; #endif /* dirent struct doesn't have d_type, do it the slow way ... */ - path[0] = '\0'; - fill_pathname_join(path, rdir->orig_path, retro_vfs_dirent_get_name_impl(rdir), sizeof(path)); + fill_pathname_join_special(path, rdir->orig_path, retro_vfs_dirent_get_name_impl(rdir), sizeof(path)); if (stat(path, &buf) < 0) return false; return S_ISDIR(buf.st_mode); @@ -1316,8 +1223,6 @@ int retro_vfs_closedir_impl(libretro_vfs_implementation_dir *rdir) sceIoDclose(rdir->directory); #elif defined(__PSL1GHT__) || defined(__PS3__) rdir->error = sysFsClosedir(rdir->directory); -#elif defined(ORBIS) - orbisDclose(rdir->directory); #else if (rdir->directory) closedir(rdir->directory);