Unify all the SDL_*RunApp() functions into just SDL_RunApp()

makes the SDL_main code shorter

Also added a generic SDL_RunApp() implementation for platforms that
don't really need it.

Some platforms (that use SDL_main but haven't been ported yet) are
still missing, but are added in the following commits.

CMakeLists.txt

@@ -515,6 +515,7 @@ file(GLOB SOURCE_FILES
   ${SDL3_SOURCE_DIR}/src/*.c
   ${SDL3_SOURCE_DIR}/src/atomic/*.c
   ${SDL3_SOURCE_DIR}/src/audio/*.c
+  ${SDL3_SOURCE_DIR}/src/core/*.c
   ${SDL3_SOURCE_DIR}/src/cpuinfo/*.c
   ${SDL3_SOURCE_DIR}/src/dynapi/*.c
   ${SDL3_SOURCE_DIR}/src/events/*.c

build-scripts/fnsince.pl

@@ -92,7 +92,6 @@ foreach my $release (@releases) {
 #  until a later release, but are available in the older release.
 $funcs{'SDL_WinRTGetFSPathUNICODE'} = '2.0.3';
 $funcs{'SDL_WinRTGetFSPathUTF8'} = '2.0.3';
-$funcs{'SDL_WinRTRunApp'} = '2.0.3';
 
 if (not defined $wikipath) {
     foreach my $release (@releases) {

include/SDL3/SDL_main.h

@@ -43,11 +43,13 @@
 /* On WinRT, SDL provides a main function that initializes CoreApplication,
    creating an instance of IFrameworkView in the process.
 
-   Please note that #include'ing SDL_main.h is not enough to get a main()
-   function working.  In non-XAML apps, the file,
-   src/main/winrt/SDL_WinRT_main_NonXAML.cpp, or a copy of it, must be compiled
-   into the app itself.  In XAML apps, the function, SDL_WinRTRunApp must be
-   called, with a pointer to the Direct3D-hosted XAML control passed in.
+   Ideally, #include'ing SDL_main.h is enough to get a main() function working.
+   However, that requires the source file your main() is in to be compiled
+   as C++ *and* with the /ZW compiler flag. If that's not feasible, add an
+   otherwise empty .cpp file that only contains `#include <SDL3/SDL_main.h>`
+   and build that with /ZW (still include SDL_main.h in your other file with main()!).
+   In XAML apps, instead the function SDL_RunApp() must be called with a pointer
+   to the Direct3D-hosted XAML control passed in as the "reserved" argument.
 */
 #define SDL_MAIN_NEEDED
 
@@ -57,7 +59,7 @@
    If you prefer to write your own WinMain-function instead of having SDL
    provide one that calls your main() function,
    #define SDL_MAIN_HANDLED before #include'ing SDL_main.h
-   and call the SDL_GDKRunApp function from your entry point.
+   and call the SDL_RunApp function from your entry point.
 */
 #define SDL_MAIN_NEEDED
 
@@ -161,6 +163,31 @@ extern SDLMAIN_DECLSPEC int SDL_main(int argc, char *argv[]);
  */
 extern DECLSPEC void SDLCALL SDL_SetMainReady(void);
 
+/**
+ * Initializes and launches an SDL application, by doing platform-specific
+ * initialization before calling your mainFunction and cleanups after it returns,
+ * if that is needed for a specific platform, otherwise it just calls mainFunction.
+ * You can use this if you want to use your own main() implementation
+ * without using SDL_main (like when using SDL_MAIN_HANDLED).
+ * When using this, you do *not* need SDL_SetMainReady().
+ *
+ * \param argc The argc parameter from the application's main() function,
+ *             or 0 if the platform's main-equivalent has no argc
+ * \param argv The argv parameter from the application's main() function,
+ *             or NULL  if the platform's main-equivalent has no argv
+ * \param mainFunction Your SDL app's C-style main(), an SDL_main_func.
+ *                     NOT the function you're calling this from!
+ *                     Its name doesn't matter, but its signature must be
+ *                     like int my_main(int argc, char* argv[])
+ * \param reserved should be NULL (reserved for future use, will probably
+ *                 be platform-specific then)
+ * \return the return value from mainFunction: 0 on success, -1 on failure;
+ *         SDL_GetError() might have more information on the failure
+ *
+ * \since This function is available since SDL 3.0.0.
+ */
+extern DECLSPEC int SDLCALL SDL_RunApp(int argc, char* argv[], SDL_main_func mainFunction, void * reserved);
+
 #if defined(__WIN32__) || defined(__GDK__)
 
 /**
@@ -207,93 +234,35 @@ extern DECLSPEC void SDLCALL SDL_UnregisterApp(void);
 
 #endif /* defined(__WIN32__) || defined(__GDK__) */
 
-#ifdef __WIN32__
-
-/**
- * Initialize and launch an SDL/Win32 (classic WinAPI) application.
- *
- * \param mainFunction the SDL app's C-style main(), an SDL_main_func
- * \param reserved reserved for future use; should be NULL
- * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve
- *          more information on the failure.
- *
- * \since This function is available since SDL 3.0.0.
- */
-extern DECLSPEC int SDLCALL SDL_Win32RunApp(SDL_main_func mainFunction, void * reserved);
-
-#endif /* __WIN32__ */
 
 #ifdef __WINRT__
 
-/**
- * Initialize and launch an SDL/WinRT application.
- *
- * \param mainFunction the SDL app's C-style main(), an SDL_main_func
- * \param reserved reserved for future use; should be NULL
- * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve
- *          more information on the failure.
- *
- * \since This function is available since SDL 2.0.3.
- */
-extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * reserved);
+/* for compatibility with SDL2's function of this name */
+#define SDL_WinRTRunApp(MAIN_FUNC, RESERVED)  SDL_RunApp(0, NULL, MAIN_FUNC, RESERVED)
 
 #endif /* __WINRT__ */
 
 #if defined(__IOS__)
 
-/**
- * Initializes and launches an SDL application.
- *
- * \param argc The argc parameter from the application's main() function
- * \param argv The argv parameter from the application's main() function
- * \param mainFunction The SDL app's C-style main(), an SDL_main_func
- * \return the return value from mainFunction
- *
- * \since This function is available since SDL 3.0.0.
- */
-extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_func mainFunction);
+/* for compatibility with SDL2's function of this name */
+#define SDL_UIKitRunApp(ARGC, ARGV, MAIN_FUNC)  SDL_RunApp(ARGC, ARGV, MAIN_FUNC, NULL)
 
 #endif /* __IOS__ */
 
 #ifdef __GDK__
 
-/**
- * Initialize and launch an SDL GDK application.
- *
- * \param mainFunction the SDL app's C-style main(), an SDL_main_func
- * \param reserved reserved for future use; should be NULL
- * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve
- *          more information on the failure.
- *
- * \since This function is available since SDL 3.0.0.
- */
-extern DECLSPEC int SDLCALL SDL_GDKRunApp(SDL_main_func mainFunction, void *reserved);
+/* for compatibility with SDL2's function of this name */
+#define SDL_GDKRunApp(MAIN_FUNC, RESERVED)  SDL_RunApp(0, NULL, MAIN_FUNC, RESERVED)
 
 /**
  * Callback from the application to let the suspend continue.
  *
- * \since This function is available since SDL 3.0.0.
+ * \since This function is available since SDL 2.28.0.
  */
 extern DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void);
 
 #endif /* __GDK__ */
 
-#ifdef __3DS__
-
-/**
- * Initializes and launches an SDL application.
- *
- * \param argc The argc parameter from the application's main() function
- * \param argv The argv parameter from the application's main() function
- * \param mainFunction The SDL app's C-style main(), an SDL_main_func
- * \return the return value from mainFunction
- *
- * \since This function is available since SDL 3.0.0.
- */
-extern DECLSPEC int SDLCALL SDL_N3DSRunApp(int argc, char *argv[], SDL_main_func mainFunction);
-
-#endif /* __3DS__ */
-
 #ifdef __cplusplus
 }
 #endif

include/SDL3/SDL_main_impl.h

@@ -72,7 +72,7 @@ typedef char* LPSTR;
 int
 console_wmain(int argc, wchar_t *wargv[], wchar_t *wenvp)
 {
-    return SDL_Win32RunApp(SDL_main, NULL);
+    return SDL_RunApp(0, NULL, SDL_main, NULL);
 }
 
 #else /* ANSI */
@@ -81,7 +81,7 @@ console_wmain(int argc, wchar_t *wargv[], wchar_t *wenvp)
 int
 console_ansi_main(int argc, char *argv[])
 {
-    return SDL_Win32RunApp(SDL_main, NULL);
+    return SDL_RunApp(0, NULL, SDL_main, NULL);
 }
 #endif /* UNICODE/ANSI */
 
@@ -91,11 +91,7 @@ console_ansi_main(int argc, char *argv[])
 int WINAPI
 WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR szCmdLine, int sw)
 {
-#ifdef __GDK__
-    return SDL_GDKRunApp(SDL_main, NULL);
-#else
-    return SDL_Win32RunApp(SDL_main, NULL);
-#endif
+    return SDL_RunApp(0, NULL, SDL_main, NULL);
 }
 
 #ifdef __cplusplus
@@ -156,31 +152,11 @@ WinMain(HINSTANCE hInst, HINSTANCE hPrev, LPSTR szCmdLine, int sw)
 
 int CALLBACK WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
 {
-    return SDL_WinRTRunApp(SDL_main, NULL);
+    return SDL_RunApp(0, NULL, SDL_main, NULL);
 }
 
 /* end of WinRT impl */
-#elif defined(__IOS__) || defined(__TVOS__)
-
-#include <SDL3/begin_code.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-int main(int argc, char *argv[])
-{
-    return SDL_UIKitRunApp(argc, argv, SDL_main);
-}
-
-#ifdef __cplusplus
-} /* extern "C" */
-#endif
-
-#include <SDL3/close_code.h>
-
-/* end of __IOS__ and __TVOS__ impls */
-#elif defined(__3DS__)
+#elif defined(__IOS__) || defined(__TVOS__) || defined(__3DS__)
 
 #include <SDL3/begin_code.h>
 
@@ -190,7 +166,7 @@ extern "C" {
 
 int main(int argc, char *argv[])
 {
-    return SDL_N3DSRunApp(argc, argv, SDL_main);
+    return SDL_RunApp(argc, argv, SDL_main, NULL);
 }
 
 #ifdef __cplusplus
@@ -199,7 +175,7 @@ int main(int argc, char *argv[])
 
 #include <SDL3/close_code.h>
 
-/* end of __3DS__ impl */
+/* end of __IOS__, __3DS__, __TVOS__ impls */
 
 /* TODO: remaining platforms */
 

src/core/SDL_runapp.c

@@ -0,0 +1,45 @@
+/*
+  Simple DirectMedia Layer
+  Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
+
+  This software is provided 'as-is', without any express or implied
+  warranty.  In no event will the authors be held liable for any damages
+  arising from the use of this software.
+
+  Permission is granted to anyone to use this software for any purpose,
+  including commercial applications, and to alter it and redistribute it
+  freely, subject to the following restrictions:
+
+  1. The origin of this software must not be misrepresented; you must not
+     claim that you wrote the original software. If you use this software
+     in a product, an acknowledgment in the product documentation would be
+     appreciated but is not required.
+  2. Altered source versions must be plainly marked as such, and must not be
+     misrepresented as being the original software.
+  3. This notice may not be removed or altered from any source distribution.
+*/
+#include "SDL_internal.h"
+
+/* Most platforms that use/need SDL_main have their own SDL_RunApp() implementation.
+ * If not, you can special case it here by appending || defined(__YOUR_PLATFORM__) */
+#if ( !defined(SDL_MAIN_NEEDED) && !defined(SDL_MAIN_AVAILABLE) ) || defined(__ANDROID__)
+
+DECLSPEC int
+SDL_RunApp(int argc, char* argv[], SDL_main_func mainFunction, void * reserved)
+{
+    char empty[1] = {0};
+    char* argvdummy[2] = { empty, NULL };
+
+    (void)reserved;
+
+    if(argv == NULL)
+    {
+        argc = 0;
+        /* make sure argv isn't NULL, in case some user code doesn't like that */
+        argv = argvdummy;
+    }
+
+    return mainFunction(argc, argv);
+}
+
+#endif

src/core/gdk/SDL_gdk.cpp

@@ -84,7 +84,7 @@ OutOfMemory(void)
 /* Gets the arguments with GetCommandLine, converts them to argc and argv
    and calls SDL_main */
 extern "C" DECLSPEC int
-SDL_GDKRunApp(SDL_main_func mainFunction, void *reserved)
+SDL_RunApp(int, char**, SDL_main_func mainFunction, void *reserved)
 {
     LPWSTR *argvw;
     char **argv;

src/core/n3ds/SDL_n3ds.c

@@ -26,7 +26,7 @@
 #include <3ds.h>
 
 DECLSPEC int
-SDL_N3DSRunApp(int argc, char *argv[], SDL_main_func mainFunction)
+SDL_RunApp(int argc, char* argv[], SDL_main_func mainFunction, void * reserved)
 {
     int result;
     /* init */

src/core/windows/SDL_windows.c

@@ -331,7 +331,8 @@ void WIN_RectToRECT(const SDL_Rect *sdlrect, RECT *winrect)
     winrect->bottom = sdlrect->y + sdlrect->h - 1;
 }
 
-/* SDL_Win32RunApp(), which does most of the SDL_main work for Win32 */
+/* Win32-specific SDL_RunApp(), which does most of the SDL_main work,
+  based on SDL_windows_main.c, placed in the public domain by Sam Lantinga  4/13/98 */
 #ifdef __WIN32__
 
 #include <shellapi.h> /* CommandLineToArgvW() */
@@ -345,7 +346,7 @@ OutOfMemory(void)
 }
 
 DECLSPEC int
-SDL_Win32RunApp(SDL_main_func mainFunction, void * xamlBackgroundPanel)
+SDL_RunApp(int _argc, char* _argv[], SDL_main_func mainFunction, void * reserved)
 {
 
     /* Gets the arguments with GetCommandLine, converts them to argc and argv
@@ -355,6 +356,8 @@ SDL_Win32RunApp(SDL_main_func mainFunction, void * xamlBackgroundPanel)
     char **argv;
     int i, argc, result;
 
+    (void)_argc; (void)_argv; (void)reserved;
+
     argvw = CommandLineToArgvW(GetCommandLineW(), &argc);
     if (argvw == NULL) {
         return OutOfMemory();

src/core/winrt/SDL_winrtapp_common.cpp

@@ -28,7 +28,7 @@
 int (*WINRT_SDLAppEntryPoint)(int, char **) = NULL;
 
 extern "C" DECLSPEC int
-SDL_WinRTRunApp(SDL_main_func mainFunction, void *xamlBackgroundPanel)
+SDL_RunApp(int, char**, SDL_main_func mainFunction, void * xamlBackgroundPanel)
 {
     if (xamlBackgroundPanel) {
         return SDL_WinRTInitXAMLApp(mainFunction, xamlBackgroundPanel);

src/dynapi/SDL_dynapi.sym

@@ -521,9 +521,6 @@ SDL3_0.0.0 {
     SDL_SetMainReady;
     SDL_RegisterApp;
     SDL_UnregisterApp;
-    SDL_WinRTRunApp;
-    SDL_UIKitRunApp;
-    SDL_GDKRunApp;
     SDL_GDKSuspendComplete;
     SDL_GetBasePath;
     SDL_GetPrefPath;
@@ -861,7 +858,7 @@ SDL3_0.0.0 {
     SDL_DelayNS;
     SDL_GetEventState;
     SDL_GetRenderDriver;
-    SDL_Win32RunApp;
+    SDL_RunApp;
     # extra symbols go here (don't modify this line)
   local: *;
 };

src/dynapi/SDL_dynapi_overrides.h

@@ -554,7 +554,6 @@
 #define SDL_GetAssertionHandler SDL_GetAssertionHandler_REAL
 #define SDL_DXGIGetOutputInfo SDL_DXGIGetOutputInfo_REAL
 #define SDL_RenderIsClipEnabled SDL_RenderIsClipEnabled_REAL
-#define SDL_WinRTRunApp SDL_WinRTRunApp_REAL
 #define SDL_WarpMouseGlobal SDL_WarpMouseGlobal_REAL
 #define SDL_WinRTGetFSPathUNICODE SDL_WinRTGetFSPathUNICODE_REAL
 #define SDL_WinRTGetFSPathUTF8 SDL_WinRTGetFSPathUTF8_REAL
@@ -693,7 +692,6 @@
 #define SDL_RenderCopyF SDL_RenderCopyF_REAL
 #define SDL_RenderCopyExF SDL_RenderCopyExF_REAL
 #define SDL_GetTouchDeviceType SDL_GetTouchDeviceType_REAL
-#define SDL_UIKitRunApp SDL_UIKitRunApp_REAL
 #define SDL_SIMDGetAlignment SDL_SIMDGetAlignment_REAL
 #define SDL_SIMDAlloc SDL_SIMDAlloc_REAL
 #define SDL_SIMDFree SDL_SIMDFree_REAL
@@ -858,7 +856,6 @@
 #define SDL_RenderGetD3D12Device SDL_RenderGetD3D12Device_REAL
 #define SDL_utf8strnlen SDL_utf8strnlen_REAL
 #define SDL_GDKGetTaskQueue SDL_GDKGetTaskQueue_REAL
-#define SDL_GDKRunApp SDL_GDKRunApp_REAL
 #define SDL_GetOriginalMemoryFunctions SDL_GetOriginalMemoryFunctions_REAL
 #define SDL_ResetKeyboard SDL_ResetKeyboard_REAL
 #define SDL_GetDefaultAudioInfo SDL_GetDefaultAudioInfo_REAL
@@ -885,5 +882,4 @@
 #define SDL_DelayNS SDL_DelayNS_REAL
 #define SDL_GetEventState SDL_GetEventState_REAL
 #define SDL_GetRenderDriver SDL_GetRenderDriver_REAL
-#define SDL_Win32RunApp SDL_Win32RunApp_REAL
-#define SDL_N3DSRunApp SDL_N3DSRunApp_REAL
+#define SDL_RunApp SDL_RunApp_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -583,7 +583,6 @@ SDL_DYNAPI_PROC(SDL_bool,SDL_DXGIGetOutputInfo,(int a, int *b, int *c),(a,b,c),r
 #endif
 SDL_DYNAPI_PROC(SDL_bool,SDL_RenderIsClipEnabled,(SDL_Renderer *a),(a),return)
 #ifdef __WINRT__
-SDL_DYNAPI_PROC(int,SDL_WinRTRunApp,(SDL_main_func a, void *b),(a,b),return)
 SDL_DYNAPI_PROC(const wchar_t*,SDL_WinRTGetFSPathUNICODE,(SDL_WinRT_Path a),(a),return)
 SDL_DYNAPI_PROC(const char*,SDL_WinRTGetFSPathUTF8,(SDL_WinRT_Path a),(a),return)
 #endif
@@ -744,9 +743,6 @@ SDL_DYNAPI_PROC(int,SDL_RenderFillRectsF,(SDL_Renderer *a, const SDL_FRect *b, i
 SDL_DYNAPI_PROC(int,SDL_RenderCopyF,(SDL_Renderer *a, SDL_Texture *b, const SDL_Rect *c, const SDL_FRect *d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(int,SDL_RenderCopyExF,(SDL_Renderer *a, SDL_Texture *b, const SDL_Rect *c, const SDL_FRect *d, const double e, const SDL_FPoint *f, const SDL_RendererFlip g),(a,b,c,d,e,f,g),return)
 SDL_DYNAPI_PROC(SDL_TouchDeviceType,SDL_GetTouchDeviceType,(SDL_TouchID a),(a),return)
-#ifdef __IOS__
-SDL_DYNAPI_PROC(int,SDL_UIKitRunApp,(int a, char *b[], SDL_main_func c),(a,b,c),return)
-#endif
 SDL_DYNAPI_PROC(size_t,SDL_SIMDGetAlignment,(void),(),return)
 SDL_DYNAPI_PROC(void*,SDL_SIMDAlloc,(const size_t a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_SIMDFree,(void *a),(a),)
@@ -931,7 +927,6 @@ SDL_DYNAPI_PROC(size_t,SDL_utf8strnlen,(const char *a, size_t b),(a,b),return)
 
 #if defined(__GDK__)
 SDL_DYNAPI_PROC(int,SDL_GDKGetTaskQueue,(XTaskQueueHandle *a),(a),return)
-SDL_DYNAPI_PROC(int,SDL_GDKRunApp,(SDL_main_func a, void *b),(a,b),return)
 #endif
 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(void,SDL_ResetKeyboard,(void),(),)
@@ -961,9 +956,4 @@ SDL_DYNAPI_PROC(Uint64,SDL_GetTicksNS,(void),(),return)
 SDL_DYNAPI_PROC(void,SDL_DelayNS,(Uint64 a),(a),)
 SDL_DYNAPI_PROC(Uint8,SDL_GetEventState,(Uint32 a),(a),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetRenderDriver,(int a),(a),return)
-#if defined(__WIN32__)
-SDL_DYNAPI_PROC(int,SDL_Win32RunApp,(SDL_main_func a, void *b),(a,b),return)
-#endif
-#if defined(__3DS__)
-SDL_DYNAPI_PROC(int,SDL_N3DSRunApp,(int a, char *b[], SDL_main_func c),(a,b,c),return)
-#endif
+SDL_DYNAPI_PROC(int,SDL_RunApp,(int a, char* b[], SDL_main_func c, void *d),(a,b,c,d),return)

src/main/windows/SDL_windows_main.c

@@ -1,7 +1,7 @@
 /*
     SDL_windows_main.c, placed in the public domain by Sam Lantinga  4/13/98
 
-    Nothing to do here, the code moved into SDL_main_impl.h and SDL_windows.c (SDL_Win32RunApp())
+    Nothing to do here, the code moved into SDL_main_impl.h and SDL_windows.c (SDL_RunApp())
     TODO: remove this file
 */
 

src/video/uikit/SDL_uikitappdelegate.m

@@ -47,7 +47,7 @@ static int forward_argc;
 static char **forward_argv;
 static int exit_status;
 
-int SDL_UIKitRunApp(int argc, char *argv[], SDL_main_func mainFunction)
+int SDL_RunApp(int argc, char* argv[], SDL_main_func mainFunction, void * reserved)
 {
     int i;