main: SDL_AppQuit() now reports the result value.

Fixes libsdl-org#10994.

docs/README-main-functions.md

@@ -190,7 +190,7 @@ to SDL_EVENT_QUIT, etc.
 Finally:
 
 ```c
-void SDL_AppQuit(void *appstate);
+void SDL_AppQuit(void *appstate, SDL_AppResult result);
 ```
 
 This is called once before terminating the app--assuming the app isn't being
@@ -201,3 +201,6 @@ from main(), so atexit handles will run, if your platform supports that.
 
 If you set `*appstate` during SDL_AppInit, this is where you should free that
 data, as this pointer will not be provided to your app again.
+
+The SDL_AppResult value that terminated the app is provided here, in case
+it's useful to know if this was a successful or failing run of the app.

examples/audio/01-simple-playback/simple-playback.c

@@ -92,7 +92,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     /* SDL will clean up the window/renderer for us. */
 }

examples/audio/02-simple-playback-callback/simple-playback-callback.c

@@ -104,7 +104,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     /* SDL will clean up the window/renderer for us. */
 }

examples/audio/03-load-wav/load-wav.c

@@ -93,7 +93,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_free(wav_data);  /* strictly speaking, this isn't necessary because the process is ending, but it's good policy. */
     /* SDL will clean up the window/renderer for us. */

examples/camera/01-read-and-draw/read-and-draw.c

@@ -103,7 +103,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_CloseCamera(camera);
     SDL_DestroyTexture(texture);

examples/game/01-snake/snake.c

@@ -320,7 +320,7 @@ SDL_AppResult SDL_AppEvent(void *appstate, SDL_Event *event)
     return SDL_APP_CONTINUE;
 }
 
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     if (appstate != NULL) {
         AppState *as = (AppState *)appstate;

examples/pen/01-drawing-lines/drawing-lines.c

@@ -96,7 +96,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_DestroyTexture(render_target);
     /* SDL will clean up the window/renderer for us. */

examples/renderer/01-clear/clear.c

@@ -59,7 +59,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     /* SDL will clean up the window/renderer for us. */
 }

examples/renderer/02-primitives/primitives.c

@@ -86,7 +86,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     /* SDL will clean up the window/renderer for us. */
 }

examples/renderer/03-lines/lines.c

@@ -84,7 +84,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     /* SDL will clean up the window/renderer for us. */
 }

examples/renderer/04-points/points.c

@@ -109,7 +109,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     /* SDL will clean up the window/renderer for us. */
 }

examples/renderer/05-rectangles/rectangles.c

@@ -103,7 +103,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     /* SDL will clean up the window/renderer for us. */
 }

examples/renderer/06-textures/textures.c

@@ -117,7 +117,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_DestroyTexture(texture);
     /* SDL will clean up the window/renderer for us. */

examples/renderer/07-streaming-textures/streaming-textures.c

@@ -99,7 +99,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_DestroyTexture(texture);
     /* SDL will clean up the window/renderer for us. */

examples/renderer/08-rotating-textures/rotating-textures.c

@@ -103,7 +103,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_DestroyTexture(texture);
     /* SDL will clean up the window/renderer for us. */

examples/renderer/09-scaling-textures/scaling-textures.c

@@ -100,7 +100,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_DestroyTexture(texture);
     /* SDL will clean up the window/renderer for us. */

examples/renderer/10-geometry/geometry.c

@@ -156,7 +156,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_DestroyTexture(texture);
     /* SDL will clean up the window/renderer for us. */

examples/renderer/11-color-mods/color-mods.c

@@ -124,7 +124,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_DestroyTexture(texture);
     /* SDL will clean up the window/renderer for us. */

examples/renderer/14-viewport/viewport.c

@@ -126,7 +126,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_DestroyTexture(texture);
     /* SDL will clean up the window/renderer for us. */

examples/renderer/15-cliprect/cliprect.c

@@ -127,7 +127,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_DestroyTexture(texture);
     /* SDL will clean up the window/renderer for us. */

examples/renderer/17-read-pixels/read-pixels.c

@@ -167,7 +167,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_DestroyTexture(converted_texture);
     SDL_DestroyTexture(texture);

examples/template.c

@@ -44,7 +44,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
 }
 
 /* This function runs once at shutdown. */
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     /* SDL will clean up the window/renderer for us. */
 }

include/SDL3/SDL_init.h

@@ -96,7 +96,7 @@ typedef enum SDL_AppResult
 typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]);
 typedef SDL_AppResult (SDLCALL *SDL_AppIterate_func)(void *appstate);
 typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *event);
-typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate);
+typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result);
 
 /**
  * Initialize the SDL library.

include/SDL3/SDL_main.h

@@ -372,14 +372,15 @@ extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, SDL_E
  * resources to it should be cleaned up here.
  *
  * \param appstate an optional pointer, provided by the app in SDL_AppInit.
+ * \param result the result code that terminated the app (success or failure).
  *
  * \threadsafety This function is not thread safe.
  *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AppInit
  */
-extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate);
+extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate, SDL_AppResult result);
 
 #endif  /* SDL_MAIN_USE_CALLBACKS */
 

src/main/SDL_main_callbacks.c

@@ -130,10 +130,10 @@ SDL_AppResult SDL_IterateMainCallbacks(bool pump_events)
     return rc;
 }
 
-void SDL_QuitMainCallbacks(void)
+void SDL_QuitMainCallbacks(SDL_AppResult result)
 {
     SDL_RemoveEventWatch(SDL_MainCallbackEventWatcher, NULL);
-    SDL_main_quit_callback(SDL_main_appstate);
+    SDL_main_quit_callback(SDL_main_appstate, result);
     SDL_main_appstate = NULL;  // just in case.
 
     // for symmetry, you should explicitly Quit what you Init, but we might come through here uninitialized and SDL_Quit() will clear everything anyhow.

src/main/SDL_main_callbacks.h

@@ -25,7 +25,7 @@
 bool SDL_HasMainCallbacks(void);
 SDL_AppResult SDL_InitMainCallbacks(int argc, char *argv[], SDL_AppInit_func appinit, SDL_AppIterate_func _appiter, SDL_AppEvent_func _appevent, SDL_AppQuit_func _appquit);
 SDL_AppResult SDL_IterateMainCallbacks(bool pump_events);
-void SDL_QuitMainCallbacks(void);
+void SDL_QuitMainCallbacks(SDL_AppResult result);
 
 #endif // SDL_main_callbacks_h_
 

src/main/emscripten/SDL_sysmain_callbacks.c

@@ -28,7 +28,7 @@ static void EmscriptenInternalMainloop(void)
 {
     const SDL_AppResult rc = SDL_IterateMainCallbacks(true);
     if (rc != SDL_APP_CONTINUE) {
-        SDL_QuitMainCallbacks();
+        SDL_QuitMainCallbacks(rc);
         emscripten_cancel_main_loop();  // kill" the mainloop, so it stops calling back into it.
         exit((rc == SDL_APP_FAILURE) ? 1 : 0);  // hopefully this takes down everything else, too.
     }
@@ -40,7 +40,7 @@ int SDL_EnterAppMainCallbacks(int argc, char* argv[], SDL_AppInit_func appinit,
     if (rc == SDL_APP_CONTINUE) {
         emscripten_set_main_loop(EmscriptenInternalMainloop, 0, 0);  // run at refresh rate, don't throw an exception since we do an orderly return.
     } else {
-        SDL_QuitMainCallbacks();
+        SDL_QuitMainCallbacks(rc);
     }
     return (rc == SDL_APP_FAILURE) ? 1 : 0;
 }

src/main/generic/SDL_sysmain_callbacks.c

@@ -75,7 +75,7 @@ int SDL_EnterAppMainCallbacks(int argc, char* argv[], SDL_AppInit_func appinit,
 
         SDL_RemoveHintCallback(SDL_HINT_MAIN_CALLBACK_RATE, MainCallbackRateHintChanged, NULL);
     }
-    SDL_QuitMainCallbacks();
+    SDL_QuitMainCallbacks(rc);
 
     return (rc == SDL_APP_FAILURE) ? 1 : 0;
 }

src/main/ios/SDL_sysmain_callbacks.m

@@ -55,7 +55,7 @@ - (void)appIteration:(CADisplayLink *)sender
         [self.displayLink invalidate];
         self.displayLink = nil;
         globalDisplayLink = nil;
-        SDL_QuitMainCallbacks();
+        SDL_QuitMainCallbacks(rc);
         SDL_UpdateLifecycleObserver();
         exit((rc == SDL_APP_FAILURE) ? 1 : 0);
     }
@@ -66,16 +66,18 @@ - (void)appIteration:(CADisplayLink *)sender
 // When we return from here, we're living in the RunLoop, and a CADisplayLink is firing regularly for us.
 int SDL_EnterAppMainCallbacks(int argc, char* argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit)
 {
-    const SDL_AppResult rc = SDL_InitMainCallbacks(argc, argv, appinit, appiter, appevent, appquit);
+    SDL_AppResult rc = SDL_InitMainCallbacks(argc, argv, appinit, appiter, appevent, appquit);
     if (rc == SDL_APP_CONTINUE) {
         globalDisplayLink = [[SDLIosMainCallbacksDisplayLink alloc] init:appiter quitfunc:appquit];
-        if (globalDisplayLink != nil) {
+        if (globalDisplayLink == nil) {
+            rc = SDL_APP_FAILURE;
+        } else {
             return 0;  // this will fall all the way out of SDL_main, where UIApplicationMain will keep running the RunLoop.
         }
     }
 
     // appinit requested quit, just bounce out now.
-    SDL_QuitMainCallbacks();
+    SDL_QuitMainCallbacks(rc);
     exit((rc == SDL_APP_FAILURE) ? 1 : 0);
 
     return 1;  // just in case.

test/loopwave.c

@@ -127,7 +127,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
     return fillerup();
 }
 
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_DestroyAudioStream(stream);
     SDL_free(wave.sound);

test/testaudio.c

@@ -1256,7 +1256,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
     return SDL_APP_CONTINUE;
 }
 
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     while (things) {
         DestroyThing(things);  /* make sure all the audio devices are closed, etc. */

test/testaudiorecording.c

@@ -196,7 +196,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
     return SDL_APP_CONTINUE;
 }
 
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_Log("Shutting down.\n");
     const SDL_AudioDeviceID devid_in = SDL_GetAudioStreamDevice(stream_in);

test/testcamera.c

@@ -353,7 +353,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
     return SDL_APP_CONTINUE;
 }
 
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_ReleaseCameraFrame(camera, frame_current);
     SDL_CloseCamera(camera);

test/testdropfile.c

@@ -114,7 +114,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
     return SDL_APP_CONTINUE;
 }
 
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     dropfile_dialog *dialog = appstate;
     if (dialog) {

test/testgpu_simple_clear.c

@@ -110,7 +110,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
     return SDL_APP_CONTINUE;
 }
 
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     /* Print out some timing information */
     const Uint64 now = SDL_GetTicks();

test/testpen.c

@@ -273,7 +273,7 @@ SDL_AppResult SDL_AppIterate(void *appstate)
     return SDL_APP_CONTINUE;
 }
 
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     Pen *i, *next;
     for (i = pens.next; i != NULL; i = next) {

test/testsprite.c

@@ -42,7 +42,7 @@ static bool suspend_when_occluded;
 /* -1: infinite random moves (default); >=0: enables N deterministic moves */
 static int iterations = -1;
 
-void SDL_AppQuit(void *appstate)
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
 {
     SDL_free(sprites);
     SDL_free(positions);