upgrade SDL3 to d4b80726142d9108f16d4806c09779d612501608

Frameworks/SDL3.xcframework/macos-arm64_x86_64/SDL3.framework/Versions/A/Headers/SDL_init.h

@@ -31,6 +31,7 @@
 
 #include <SDL3/SDL_stdinc.h>
 #include <SDL3/SDL_error.h>
+#include <SDL3/SDL_events.h>
 
 #include <SDL3/SDL_begin_code.h>
 /* Set up for C function definitions, even when using C++ */
@@ -66,6 +67,38 @@ typedef Uint32 SDL_InitFlags;
 #define SDL_INIT_SENSOR     0x00008000u /**< `SDL_INIT_SENSOR` implies `SDL_INIT_EVENTS` */
 #define SDL_INIT_CAMERA     0x00010000u /**< `SDL_INIT_CAMERA` implies `SDL_INIT_EVENTS` */
 
+/**
+ * Return values for optional main callbacks.
+ *
+ * Returning SDL_APP_SUCCESS or SDL_APP_FAILURE from SDL_AppInit,
+ * SDL_AppEvent, or SDL_AppIterate will terminate the program and report
+ * success/failure to the operating system. What that means is
+ * platform-dependent. On Unix, for example, on success, the process error
+ * code will be zero, and on failure it will be 1. This interface doesn't
+ * allow you to return specific exit codes, just whether there was an error
+ * generally or not.
+ *
+ * Returning SDL_APP_CONTINUE from these functions will let the app continue
+ * to run.
+ *
+ * See
+ * [Main callbacks in SDL3](https://wiki.libsdl.org/SDL3/README/main-functions#main-callbacks-in-sdl3)
+ * for complete details.
+ *
+ * \since This enum is available since SDL 3.0.0.
+ */
+typedef enum SDL_AppResult
+{
+    SDL_APP_CONTINUE,   /**< Value that requests that the app continue from the main callbacks. */
+    SDL_APP_SUCCESS,    /**< Value that requests termination with success from the main callbacks. */
+    SDL_APP_FAILURE     /**< Value that requests termination with error from the main callbacks. */
+} 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, const SDL_Event *event);
+typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate);
+
 /**
  * Initialize the SDL library.
  *
@@ -110,8 +143,8 @@ typedef Uint32 SDL_InitFlags;
  * SDL_SetAppMetadataProperty().
  *
  * \param flags subsystem initialization flags.
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ *          for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -122,7 +155,7 @@ typedef Uint32 SDL_InitFlags;
  * \sa SDL_SetMainReady
  * \sa SDL_WasInit
  */
-extern SDL_DECLSPEC int SDLCALL SDL_Init(SDL_InitFlags flags);
+extern SDL_DECLSPEC SDL_bool SDLCALL SDL_Init(SDL_InitFlags flags);
 
 /**
  * Compatibility function to initialize the SDL library.
@@ -130,8 +163,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_Init(SDL_InitFlags flags);
  * This function and SDL_Init() are interchangeable.
  *
  * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ *          for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -139,7 +172,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_Init(SDL_InitFlags flags);
  * \sa SDL_Quit
  * \sa SDL_QuitSubSystem
  */
-extern SDL_DECLSPEC int SDLCALL SDL_InitSubSystem(SDL_InitFlags flags);
+extern SDL_DECLSPEC SDL_bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags);
 
 /**
  * Shut down specific SDL subsystems.
@@ -215,8 +248,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_Quit(void);
  *                   hash, or whatever makes sense).
  * \param appidentifier A unique string in reverse-domain format that
  *                      identifies this app ("com.example.mygame2").
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ *          for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -224,7 +257,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Quit(void);
  *
  * \sa SDL_SetAppMetadataProperty
  */
-extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier);
+extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier);
 
 /**
  * Specify metadata about your app through a set of properties.
@@ -250,7 +283,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const ch
  *   anywhere the OS shows the name of the application separately from window
  *   titles, such as volume control applets, etc. This defaults to "SDL
  *   Application".
- * - SDL_PROP_APP_METADATA_VERSION_STRING`: The version of the app that is
+ * - `SDL_PROP_APP_METADATA_VERSION_STRING`: The version of the app that is
  *   running; there are no rules on format, so "1.0.3beta2" and "April 22nd,
  *   2024" and a git hash are all valid options. This has no default.
  * - `SDL_PROP_APP_METADATA_IDENTIFIER_STRING`: A unique string that
@@ -260,16 +293,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const ch
  *   associated desktop settings and icons. If you plan to package your
  *   application in a container such as Flatpak, the app ID should match the
  *   name of your Flatpak container as well. This has no default.
- * - SDL_PROP_APP_METADATA_CREATOR_STRING`: The human-readable name of the
+ * - `SDL_PROP_APP_METADATA_CREATOR_STRING`: The human-readable name of the
  *   creator/developer/maker of this app, like "MojoWorkshop, LLC"
- * - SDL_PROP_APP_METADATA_COPYRIGHT_STRING`: The human-readable copyright
+ * - `SDL_PROP_APP_METADATA_COPYRIGHT_STRING`: The human-readable copyright
  *   notice, like "Copyright (c) 2024 MojoWorkshop, LLC" or whatnot. Keep this
  *   to one line, don't paste a copy of a whole software license in here. This
  *   has no default.
- * - SDL_PROP_APP_METADATA_URL_STRING`: A URL to the app on the web. Maybe a
+ * - `SDL_PROP_APP_METADATA_URL_STRING`: A URL to the app on the web. Maybe a
  *   product page, or a storefront, or even a GitHub repository, for user's
  *   further information This has no default.
- * - SDL_PROP_APP_METADATA_TYPE_STRING`: The type of application this is.
+ * - `SDL_PROP_APP_METADATA_TYPE_STRING`: The type of application this is.
  *   Currently this string can be "game" for a video game, "mediaplayer" for a
  *   media player, or generically "application" if nothing else applies.
  *   Future versions of SDL might add new types. This defaults to
@@ -277,8 +310,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const ch
  *
  * \param name the name of the metadata property to set.
  * \param value the value of the property, or NULL to remove that property.
- * \returns 0 on success or a negative error code on failure; call
- *          SDL_GetError() for more information.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ *          for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -287,7 +320,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadata(const char *appname, const ch
  * \sa SDL_GetAppMetadataProperty
  * \sa SDL_SetAppMetadata
  */
-extern SDL_DECLSPEC int SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value);
+extern SDL_DECLSPEC SDL_bool SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value);
 
 #define SDL_PROP_APP_METADATA_NAME_STRING         "SDL.app.metadata.name"
 #define SDL_PROP_APP_METADATA_VERSION_STRING      "SDL.app.metadata.version"