diff --git a/include/SDL3/SDL_filesystem.h b/include/SDL3/SDL_filesystem.h index a672365c07..ec0c974d8b 100644 --- a/include/SDL3/SDL_filesystem.h +++ b/include/SDL3/SDL_filesystem.h @@ -159,11 +159,11 @@ extern DECLSPEC char *SDLCALL SDL_GetPrefPath(const char *org, const char *app); * | SAVEDGAMES | Vista+ | | | | | | * | SCREENSHOTS | Vista+ | | | | | | * | TEMPLATES | X | X | | X | | | - * | VIDEOS | X | X | | X | | | + * | VIDEOS | X | X* | | X | | | * - * Note that on macOS/iOS, the Videos folder is called "Movies". + * * Note that on macOS/iOS, the Videos folder is called "Movies". * - * \sa SDL_GetPath + * \sa SDL_GetUserFolder */ typedef enum { @@ -206,13 +206,18 @@ typedef enum } SDL_Folder; /** - * Finds the most suitable OS-provided folder for @p folder, and returns its + * Finds the most suitable user folder for @p purpose, and returns its * path in OS-specific notation. * * Many OSes provide certain standard folders for certain purposes, such as * storing pictures, music or videos for a certain user. This function gives * the path for many of those special locations. * + * This function is specifically for _user_ folders, which are meant for the + * user to access and manage. For application-specific folders, meant to hold + * data for the application to manage, see SDL_GetBasePath() and + * SDL_GetPrefPath(). + * * Note that the function is expensive, and should be called once at the * beginning of the execution and kept for as long as needed. * @@ -229,7 +234,7 @@ typedef enum * * \sa SDL_Folder */ -extern DECLSPEC char *SDLCALL SDL_GetPath(SDL_Folder folder); +extern DECLSPEC char *SDLCALL SDL_GetUserFolder(SDL_Folder folder); /* Ends C function definitions when using C++ */ #ifdef __cplusplus diff --git a/src/dynapi/SDL_dynapi.sym b/src/dynapi/SDL_dynapi.sym index 751abf72b7..9a71927f74 100644 --- a/src/dynapi/SDL_dynapi.sym +++ b/src/dynapi/SDL_dynapi.sym @@ -280,7 +280,7 @@ SDL3_0.0.0 { SDL_GetNumTouchFingers; SDL_GetNumVideoDrivers; SDL_GetOriginalMemoryFunctions; - SDL_GetPath; + SDL_GetUserFolder; SDL_GetPerformanceCounter; SDL_GetPerformanceFrequency; SDL_GetPixelFormatEnumForMasks; diff --git a/src/dynapi/SDL_dynapi_overrides.h b/src/dynapi/SDL_dynapi_overrides.h index 3fefcb1954..df12bad281 100644 --- a/src/dynapi/SDL_dynapi_overrides.h +++ b/src/dynapi/SDL_dynapi_overrides.h @@ -304,7 +304,7 @@ #define SDL_GetNumTouchFingers SDL_GetNumTouchFingers_REAL #define SDL_GetNumVideoDrivers SDL_GetNumVideoDrivers_REAL #define SDL_GetOriginalMemoryFunctions SDL_GetOriginalMemoryFunctions_REAL -#define SDL_GetPath SDL_GetPath_REAL +#define SDL_GetUserFolder SDL_GetUserFolder_REAL #define SDL_GetPerformanceCounter SDL_GetPerformanceCounter_REAL #define SDL_GetPerformanceFrequency SDL_GetPerformanceFrequency_REAL #define SDL_GetPixelFormatEnumForMasks SDL_GetPixelFormatEnumForMasks_REAL diff --git a/src/dynapi/SDL_dynapi_procs.h b/src/dynapi/SDL_dynapi_procs.h index 7b93149fb7..d13d5886c0 100644 --- a/src/dynapi/SDL_dynapi_procs.h +++ b/src/dynapi/SDL_dynapi_procs.h @@ -379,7 +379,7 @@ SDL_DYNAPI_PROC(int,SDL_GetNumTouchDevices,(void),(),return) SDL_DYNAPI_PROC(int,SDL_GetNumTouchFingers,(SDL_TouchID a),(a),return) SDL_DYNAPI_PROC(int,SDL_GetNumVideoDrivers,(void),(),return) SDL_DYNAPI_PROC(void,SDL_GetOriginalMemoryFunctions,(SDL_malloc_func *a, SDL_calloc_func *b, SDL_realloc_func *c, SDL_free_func *d),(a,b,c,d),) -SDL_DYNAPI_PROC(char*,SDL_GetPath,(SDL_Folder a),(a),return) +SDL_DYNAPI_PROC(char*,SDL_GetUserFolder,(SDL_Folder a),(a),return) SDL_DYNAPI_PROC(Uint64,SDL_GetPerformanceCounter,(void),(),return) SDL_DYNAPI_PROC(Uint64,SDL_GetPerformanceFrequency,(void),(),return) SDL_DYNAPI_PROC(Uint32,SDL_GetPixelFormatEnumForMasks,(int a, Uint32 b, Uint32 c, Uint32 d, Uint32 e),(a,b,c,d,e),return) diff --git a/src/filesystem/android/SDL_sysfilesystem.c b/src/filesystem/android/SDL_sysfilesystem.c index 2a5ed9e544..d14f789213 100644 --- a/src/filesystem/android/SDL_sysfilesystem.c +++ b/src/filesystem/android/SDL_sysfilesystem.c @@ -50,7 +50,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) return NULL; } -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { /* TODO: see https://developer.android.com/reference/android/os/Environment#lfields and https://stackoverflow.com/questions/39332085/get-path-to-pictures-directory */ diff --git a/src/filesystem/cocoa/SDL_sysfilesystem.m b/src/filesystem/cocoa/SDL_sysfilesystem.m index c644495cfc..0a78a2d9aa 100644 --- a/src/filesystem/cocoa/SDL_sysfilesystem.m +++ b/src/filesystem/cocoa/SDL_sysfilesystem.m @@ -130,7 +130,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) } } -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { @autoreleasepool { #if TARGET_OS_TV diff --git a/src/filesystem/dummy/SDL_sysfilesystem.c b/src/filesystem/dummy/SDL_sysfilesystem.c index 58c91a37fa..197284cfce 100644 --- a/src/filesystem/dummy/SDL_sysfilesystem.c +++ b/src/filesystem/dummy/SDL_sysfilesystem.c @@ -37,7 +37,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) return NULL; } -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { SDL_Unsupported(); return NULL; diff --git a/src/filesystem/emscripten/SDL_sysfilesystem.c b/src/filesystem/emscripten/SDL_sysfilesystem.c index a373637419..389eff087a 100644 --- a/src/filesystem/emscripten/SDL_sysfilesystem.c +++ b/src/filesystem/emscripten/SDL_sysfilesystem.c @@ -83,7 +83,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) return retval; } -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { const char *home = NULL; char *retval; diff --git a/src/filesystem/haiku/SDL_sysfilesystem.cc b/src/filesystem/haiku/SDL_sysfilesystem.cc index 07e53766a9..466a2576a8 100644 --- a/src/filesystem/haiku/SDL_sysfilesystem.cc +++ b/src/filesystem/haiku/SDL_sysfilesystem.cc @@ -97,7 +97,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) return retval; } -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { const char *home = NULL; char *retval; diff --git a/src/filesystem/n3ds/SDL_sysfilesystem.c b/src/filesystem/n3ds/SDL_sysfilesystem.c index 27fc16e7b3..7bde831027 100644 --- a/src/filesystem/n3ds/SDL_sysfilesystem.c +++ b/src/filesystem/n3ds/SDL_sysfilesystem.c @@ -60,7 +60,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) } /* TODO */ -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { SDL_Unsupported(); return NULL; diff --git a/src/filesystem/ps2/SDL_sysfilesystem.c b/src/filesystem/ps2/SDL_sysfilesystem.c index 0636fce285..b52fdea357 100644 --- a/src/filesystem/ps2/SDL_sysfilesystem.c +++ b/src/filesystem/ps2/SDL_sysfilesystem.c @@ -103,7 +103,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) } /* TODO */ -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { SDL_Unsupported(); return NULL; diff --git a/src/filesystem/psp/SDL_sysfilesystem.c b/src/filesystem/psp/SDL_sysfilesystem.c index 3fdd719276..239e674367 100644 --- a/src/filesystem/psp/SDL_sysfilesystem.c +++ b/src/filesystem/psp/SDL_sysfilesystem.c @@ -70,7 +70,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) } /* TODO */ -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { SDL_Unsupported(); return NULL; diff --git a/src/filesystem/riscos/SDL_sysfilesystem.c b/src/filesystem/riscos/SDL_sysfilesystem.c index 37b19cbd2e..17d6625b71 100644 --- a/src/filesystem/riscos/SDL_sysfilesystem.c +++ b/src/filesystem/riscos/SDL_sysfilesystem.c @@ -200,7 +200,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) } /* TODO */ -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { SDL_Unsupported(); return NULL; diff --git a/src/filesystem/unix/SDL_sysfilesystem.c b/src/filesystem/unix/SDL_sysfilesystem.c index 145c030889..88a3a35375 100644 --- a/src/filesystem/unix/SDL_sysfilesystem.c +++ b/src/filesystem/unix/SDL_sysfilesystem.c @@ -517,7 +517,7 @@ static char *xdg_user_dir_lookup (const char *type) return NULL; } -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { const char *param = NULL; char *retval; diff --git a/src/filesystem/vita/SDL_sysfilesystem.c b/src/filesystem/vita/SDL_sysfilesystem.c index a99a1747ca..836416abfd 100644 --- a/src/filesystem/vita/SDL_sysfilesystem.c +++ b/src/filesystem/vita/SDL_sysfilesystem.c @@ -84,7 +84,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) } /* TODO */ -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { SDL_Unsupported(); return NULL; diff --git a/src/filesystem/windows/SDL_sysfilesystem.c b/src/filesystem/windows/SDL_sysfilesystem.c index 59370d2c98..2dffe4c2a2 100644 --- a/src/filesystem/windows/SDL_sysfilesystem.c +++ b/src/filesystem/windows/SDL_sysfilesystem.c @@ -177,7 +177,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) return retval; } -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { typedef HRESULT (WINAPI *pfnSHGetKnownFolderPath)(REFGUID /* REFKNOWNFOLDERID */, DWORD, HANDLE, PWSTR*); HMODULE lib = LoadLibrary(L"Shell32.dll"); @@ -346,7 +346,7 @@ char *SDL_GetPrefPath(const char *org, const char *app) return NULL; } -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { SDL_Unsupported(); return NULL; diff --git a/src/filesystem/winrt/SDL_sysfilesystem.cpp b/src/filesystem/winrt/SDL_sysfilesystem.cpp index 33218c60a0..a5e85b4a95 100644 --- a/src/filesystem/winrt/SDL_sysfilesystem.cpp +++ b/src/filesystem/winrt/SDL_sysfilesystem.cpp @@ -233,7 +233,7 @@ SDL_GetPrefPath(const char *org, const char *app) } /* TODO */ -char *SDL_GetPath(SDL_Folder folder) +char *SDL_GetUserFolder(SDL_Folder folder) { SDL_Unsupported(); return NULL;