From d4a867a256e085355a5e1657984278e061000358 Mon Sep 17 00:00:00 2001
From: Semphris <[EMAIL REDACTED]>
Date: Fri, 28 Jul 2023 13:45:37 -0400
Subject: [PATCH] Rename SDL_GetPath to SDL_GetUserFolder
The documentation has been edited accordingly, and certain parts have been clarified.
---
include/SDL3/SDL_filesystem.h | 15 ++++++++++-----
src/dynapi/SDL_dynapi.sym | 2 +-
src/dynapi/SDL_dynapi_overrides.h | 2 +-
src/dynapi/SDL_dynapi_procs.h | 2 +-
src/filesystem/android/SDL_sysfilesystem.c | 2 +-
src/filesystem/cocoa/SDL_sysfilesystem.m | 2 +-
src/filesystem/dummy/SDL_sysfilesystem.c | 2 +-
src/filesystem/emscripten/SDL_sysfilesystem.c | 2 +-
src/filesystem/haiku/SDL_sysfilesystem.cc | 2 +-
src/filesystem/n3ds/SDL_sysfilesystem.c | 2 +-
src/filesystem/ps2/SDL_sysfilesystem.c | 2 +-
src/filesystem/psp/SDL_sysfilesystem.c | 2 +-
src/filesystem/riscos/SDL_sysfilesystem.c | 2 +-
src/filesystem/unix/SDL_sysfilesystem.c | 2 +-
src/filesystem/vita/SDL_sysfilesystem.c | 2 +-
src/filesystem/windows/SDL_sysfilesystem.c | 4 ++--
src/filesystem/winrt/SDL_sysfilesystem.cpp | 2 +-
17 files changed, 27 insertions(+), 22 deletions(-)
diff --git a/include/SDL3/SDL_filesystem.h b/include/SDL3/SDL_filesystem.h
index a672365c078f..ec0c974d8b3c 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 751abf72b7c1..9a71927f7448 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 3fefcb19545f..df12bad2810f 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 7b93149fb749..d13d5886c0a1 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 2a5ed9e54495..d14f78921300 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 c644495cfc7f..0a78a2d9aa0c 100644
--- a/src/filesystem/cocoa/SDL_sysfilesystem.m
+++ b/src/filesystem/cocoa/SDL_sysfilesystem.m
@@ -130,7 +130,7 @@
}
}
-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 58c91a37fac7..197284cfce9f 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 a373637419b3..389eff087adf 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 07e53766a9fd..466a2576a851 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 27fc16e7b332..7bde83102763 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 0636fce28585..b52fdea35724 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 3fdd7192768f..239e67436743 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 37b19cbd2e5f..17d6625b711b 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 145c030889c4..88a3a35375ce 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 a99a1747cac7..836416abfdda 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 59370d2c9860..2dffe4c2a2a1 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 33218c60a0d4..a5e85b4a9541 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;