Xcode: update macOS SDL3 framework headers as well

Author: madebr

Xcode/macOS/SDL3.framework/Versions/A/Headers/SDL.h

@@ -20,7 +20,7 @@
 */
 
 /**
- * Main include header for the SDL library, version 3.3.0
+ * Main include header for the SDL library, version 3.3.3
  *
  * It is almost always best to include just this one header instead of
  * picking out individual headers included here. There are exceptions to
@@ -42,6 +42,7 @@
 #include <SDL3/SDL_clipboard.h>
 #include <SDL3/SDL_cpuinfo.h>
 #include <SDL3/SDL_dialog.h>
+#include <SDL3/SDL_dlopennote.h>
 #include <SDL3/SDL_endian.h>
 #include <SDL3/SDL_error.h>
 #include <SDL3/SDL_events.h>

Xcode/macOS/SDL3.framework/Versions/A/Headers/SDL_assert.h

@@ -126,20 +126,17 @@ extern "C" {
  */
 #define SDL_TriggerBreakpoint() TriggerABreakpointInAPlatformSpecificManner
 
-#elif defined(_MSC_VER) && _MSC_VER >= 1310
+#elif defined(__MINGW32__) || (defined(_MSC_VER) && _MSC_VER >= 1310)
     /* Don't include intrin.h here because it contains C++ code */
     extern void __cdecl __debugbreak(void);
     #define SDL_TriggerBreakpoint() __debugbreak()
 #elif defined(_MSC_VER) && defined(_M_IX86)
     #define SDL_TriggerBreakpoint() { _asm { int 0x03 }  }
-#elif defined(ANDROID) || defined(__SYMBIAN32__)
-    #include <assert.h>
-    #define SDL_TriggerBreakpoint() assert(0)
 #elif SDL_HAS_BUILTIN(__builtin_debugtrap)
     #define SDL_TriggerBreakpoint() __builtin_debugtrap()
 #elif SDL_HAS_BUILTIN(__builtin_trap)
     #define SDL_TriggerBreakpoint() __builtin_trap()
-#elif (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__))
+#elif (defined(__GNUC__) || defined(__clang__) || defined(__TINYC__)) && (defined(__i386__) || defined(__x86_64__))
     #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "int $3\n\t" )
 #elif (defined(__GNUC__) || defined(__clang__)) && defined(__riscv)
     #define SDL_TriggerBreakpoint() __asm__ __volatile__ ( "ebreak\n\t" )
@@ -179,12 +176,48 @@ extern "C" {
 #   define SDL_FUNCTION "???"
 #endif
 
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
 /**
  * A macro that reports the current file being compiled.
  *
+ * This macro is only defined if it isn't already defined, so to override it
+ * (perhaps with something that doesn't provide path information at all, so
+ * build machine information doesn't leak into public binaries), apps can
+ * define this macro before including SDL.h or SDL_assert.h.
+ *
  * \since This macro is available since SDL 3.2.0.
  */
+#define SDL_FILE    __FILE_NAME__
+
+#elif !defined(SDL_FILE)
+#ifdef __FILE_NAME__
+#define SDL_FILE    __FILE_NAME__
+#else
 #define SDL_FILE    __FILE__
+#endif
+#endif
+
+#ifdef SDL_WIKI_DOCUMENTATION_SECTION
+
+/**
+ * A macro that reports the current file being compiled, for use in
+ * assertions.
+ *
+ * This macro is only defined if it isn't already defined, so to override it
+ * (perhaps with something that doesn't provide path information at all, so
+ * build machine information doesn't leak into public binaries), apps can
+ * define this macro before including SDL_assert.h. For example, defining this
+ * to `""` will make sure no source path information is included in asserts.
+ *
+ * \since This macro is available since SDL 3.4.0.
+ */
+#define SDL_ASSERT_FILE SDL_FILE
+
+#elif !defined(SDL_ASSERT_FILE)
+#define SDL_ASSERT_FILE SDL_FILE
+#endif
+
 
 /**
  * A macro that reports the current line number of the file being compiled.
@@ -362,8 +395,8 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
 #define SDL_enabled_assert(condition) \
     do { \
         while ( !(condition) ) { \
-            static struct SDL_AssertData sdl_assert_data = { 0, 0, #condition, 0, 0, 0, 0 }; \
-            const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_FILE, SDL_LINE); \
+            static struct SDL_AssertData sdl_assert_data = { false, 0, #condition, NULL, 0, NULL, NULL }; \
+            const SDL_AssertState sdl_assert_state = SDL_ReportAssertion(&sdl_assert_data, SDL_FUNCTION, SDL_ASSERT_FILE, SDL_LINE); \
             if (sdl_assert_state == SDL_ASSERTION_RETRY) { \
                 continue; /* go again. */ \
             } else if (sdl_assert_state == SDL_ASSERTION_BREAK) { \

Xcode/macOS/SDL3.framework/Versions/A/Headers/SDL_atomic.h

@@ -596,6 +596,24 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_SetAtomicU32(SDL_AtomicU32 *a, Uint32 v);
  */
 extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAtomicU32(SDL_AtomicU32 *a);
 
+/**
+ * Add to an atomic variable.
+ *
+ * This function also acts as a full memory barrier.
+ *
+ * ***Note: If you don't know what this function is for, you shouldn't use
+ * it!***
+ *
+ * \param a a pointer to an SDL_AtomicU32 variable to be modified.
+ * \param v the desired value to add or subtract.
+ * \returns the previous value of the atomic variable.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.4.0.
+ */
+extern SDL_DECLSPEC Uint32 SDLCALL SDL_AddAtomicU32(SDL_AtomicU32 *a, int v);
+
 /**
  * Set a pointer to a new value if it is currently an old value.
  *

Xcode/macOS/SDL3.framework/Versions/A/Headers/SDL_audio.h

@@ -1336,7 +1336,7 @@ extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioSt
  * \threadsafety It is safe to call this function from any thread, as it holds
  *               a stream-specific mutex while running. Don't change the
  *               stream's format to have a different number of channels from a
- *               a different thread at the same time, though!
+ *               different thread at the same time, though!
  *
  * \since This function is available since SDL 3.2.0.
  *

Xcode/macOS/SDL3.framework/Versions/A/Headers/SDL_begin_code.h

@@ -298,7 +298,7 @@
  * // make sure this one field in a struct is aligned to 16 bytes for SIMD access.
  * typedef struct {
  *    SomeStuff stuff;
- *    float position[4] SDL_ALIGNED(16);
+ *    float SDL_ALIGNED(16) position[4];
  *    SomeOtherStuff other_stuff;
  * } MyStruct;
  *
@@ -431,7 +431,7 @@
 #endif /* SDL_INLINE not defined */
 
 #ifndef SDL_FORCE_INLINE
-#ifdef _MSC_VER
+#if defined(_MSC_VER) && (_MSC_VER >= 1200)
 #define SDL_FORCE_INLINE __forceinline
 #elif ( (defined(__GNUC__) && (__GNUC__ >= 4)) || defined(__clang__) )
 #define SDL_FORCE_INLINE __attribute__((always_inline)) static __inline__

Xcode/macOS/SDL3.framework/Versions/A/Headers/SDL_camera.h

@@ -119,7 +119,7 @@ typedef struct SDL_CameraSpec
     int width;                  /**< Frame width */
     int height;                 /**< Frame height */
     int framerate_numerator;     /**< Frame rate numerator ((num / denom) == FPS, (denom / num) == duration in seconds) */
-    int framerate_denominator;   /**< Frame rate demoninator ((num / denom) == FPS, (denom / num) == duration in seconds) */
+    int framerate_denominator;   /**< Frame rate denominator ((num / denom) == FPS, (denom / num) == duration in seconds) */
 } SDL_CameraSpec;
 
 /**
@@ -136,6 +136,20 @@ typedef enum SDL_CameraPosition
     SDL_CAMERA_POSITION_BACK_FACING
 } SDL_CameraPosition;
 
+/**
+ * The current state of a request for camera access.
+ *
+ * \since This enum is available since SDL 3.4.0.
+ *
+ * \sa SDL_GetCameraPermissionState
+ */
+typedef enum SDL_CameraPermissionState
+{
+    SDL_CAMERA_PERMISSION_STATE_DENIED = -1,
+    SDL_CAMERA_PERMISSION_STATE_PENDING,
+    SDL_CAMERA_PERMISSION_STATE_APPROVED,
+} SDL_CameraPermissionState;
+
 
 /**
  * Use this function to get the number of built-in camera drivers.
@@ -346,8 +360,9 @@ extern SDL_DECLSPEC SDL_Camera * SDLCALL SDL_OpenCamera(SDL_CameraID instance_id
  * on others the approval might be implicit and not alert the user at all.
  *
  * This function can be used to check the status of that approval. It will
- * return 0 if still waiting for user response, 1 if the camera is approved
- * for use, and -1 if the user denied access.
+ * return SDL_CAMERA_PERMISSION_STATE_PENDING if waiting for user response,
+ * SDL_CAMERA_PERMISSION_STATE_APPROVED if the camera is approved for use, and
+ * SDL_CAMERA_PERMISSION_STATE_DENIED if the user denied access.
  *
  * Instead of polling with this function, you can wait for a
  * SDL_EVENT_CAMERA_DEVICE_APPROVED (or SDL_EVENT_CAMERA_DEVICE_DENIED) event
@@ -358,8 +373,9 @@ extern SDL_DECLSPEC SDL_Camera * SDLCALL SDL_OpenCamera(SDL_CameraID instance_id
  * SDL_CloseCamera() to dispose of it.
  *
  * \param camera the opened camera device to query.
- * \returns -1 if user denied access to the camera, 1 if user approved access,
- *          0 if no decision has been made yet.
+ * \returns an SDL_CameraPermissionState value indicating if access is
+ *          granted, or `SDL_CAMERA_PERMISSION_STATE_PENDING` if the decision
+ *          is still pending.
  *
  * \threadsafety It is safe to call this function from any thread.
  *
@@ -368,7 +384,7 @@ extern SDL_DECLSPEC SDL_Camera * SDLCALL SDL_OpenCamera(SDL_CameraID instance_id
  * \sa SDL_OpenCamera
  * \sa SDL_CloseCamera
  */
-extern SDL_DECLSPEC int SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera);
+extern SDL_DECLSPEC SDL_CameraPermissionState SDLCALL SDL_GetCameraPermissionState(SDL_Camera *camera);
 
 /**
  * Get the instance ID of an opened camera.

Xcode/macOS/SDL3.framework/Versions/A/Headers/SDL_clipboard.h

@@ -106,7 +106,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text);
 /**
  * Get UTF-8 text from the clipboard.
  *
- * This functions returns an empty string if there was not enough memory left
+ * This function returns an empty string if there is not enough memory left
  * for a copy of the clipboard's content.
  *
  * \returns the clipboard text on success or an empty string on failure; call
@@ -155,7 +155,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text);
 /**
  * Get UTF-8 text from the primary selection.
  *
- * This functions returns an empty string if there was not enough memory left
+ * This function returns an empty string if there is not enough memory left
  * for a copy of the primary selection's content.
  *
  * \returns the primary selection text on success or an empty string on
@@ -194,15 +194,14 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasPrimarySelectionText(void);
  * clipboard is cleared or new data is set. The clipboard is automatically
  * cleared in SDL_Quit().
  *
- * \param userdata a pointer to provided user data.
+ * \param userdata a pointer to the provided user data.
  * \param mime_type the requested mime-type.
  * \param size a pointer filled in with the length of the returned data.
  * \returns a pointer to the data for the provided mime-type. Returning NULL
- *          or setting length to 0 will cause no data to be sent to the
- *          "receiver". It is up to the receiver to handle this. Essentially
- *          returning no data is more or less undefined behavior and may cause
- *          breakage in receiving applications. The returned data will not be
- *          freed so it needs to be retained and dealt with internally.
+ *          or setting the length to 0 will cause zero length data to be sent
+ *          to the "receiver", which should be able to handle this. The
+ *          returned data will not be freed, so it needs to be retained and
+ *          dealt with internally.
  *
  * \since This function is available since SDL 3.2.0.
  *
@@ -211,10 +210,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasPrimarySelectionText(void);
 typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const char *mime_type, size_t *size);
 
 /**
- * Callback function that will be called when the clipboard is cleared, or new
- * data is set.
+ * Callback function that will be called when the clipboard is cleared, or
+ * when new data is set.
  *
- * \param userdata a pointer to provided user data.
+ * \param userdata a pointer to the provided user data.
  *
  * \since This function is available since SDL 3.2.0.
  *
@@ -231,15 +230,16 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);
  * respond with the data for the requested mime-type.
  *
  * The size of text data does not include any terminator, and the text does
- * not need to be null terminated (e.g. you can directly copy a portion of a
+ * not need to be null-terminated (e.g., you can directly copy a portion of a
  * document).
  *
  * \param callback a function pointer to the function that provides the
  *                 clipboard data.
  * \param cleanup a function pointer to the function that cleans up the
  *                clipboard data.
  * \param userdata an opaque pointer that will be forwarded to the callbacks.
- * \param mime_types a list of mime-types that are being offered.
+ * \param mime_types a list of mime-types that are being offered. SDL copies
+ *                   the given list.
  * \param num_mime_types the number of mime-types in the mime_types list.
  * \returns true on success or false on failure; call SDL_GetError() for more
  *          information.
@@ -269,10 +269,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback
 extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void);
 
 /**
- * Get the data from clipboard for a given mime type.
+ * Get the data from the clipboard for a given mime type.
  *
  * The size of text data does not include the terminator, but the text is
- * guaranteed to be null terminated.
+ * guaranteed to be null-terminated.
  *
  * \param mime_type the mime type to read from the clipboard.
  * \param size a pointer filled in with the length of the returned data.
@@ -292,8 +292,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetClipboardData(const char *mime_type, s
 /**
  * Query whether there is data in the clipboard for the provided mime type.
  *
- * \param mime_type the mime type to check for data for.
- * \returns true if there exists data in clipboard for the provided mime type,
+ * \param mime_type the mime type to check for data.
+ * \returns true if data exists in the clipboard for the provided mime type,
  *          false if it does not.
  *
  * \threadsafety This function should only be called on the main thread.
@@ -310,7 +310,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type);
  *
  * \param num_mime_types a pointer filled with the number of mime types, may
  *                       be NULL.
- * \returns a null terminated array of strings with mime types, or NULL on
+ * \returns a null-terminated array of strings with mime types, or NULL on
  *          failure; call SDL_GetError() for more information. This should be
  *          freed with SDL_free() when it is no longer needed.
  *

Xcode/macOS/SDL3.framework/Versions/A/Headers/SDL_cpuinfo.h

@@ -344,6 +344,27 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
  */
 extern SDL_DECLSPEC size_t SDLCALL SDL_GetSIMDAlignment(void);
 
+/**
+ * Report the size of a page of memory.
+ *
+ * Different platforms might have different memory page sizes. In current
+ * times, 4 kilobytes is not unusual, but newer systems are moving to larger
+ * page sizes, and esoteric platforms might have any unexpected size.
+ *
+ * Note that this function can return 0, which means SDL can't determine the
+ * page size on this platform. It will _not_ set an error string to be
+ * retrieved with SDL_GetError() in this case! In this case, defaulting to
+ * 4096 is often a reasonable option.
+ *
+ * \returns the size of a single page of memory, in bytes, or 0 if SDL can't
+ *          determine this information.
+ *
+ * \threadsafety It is safe to call this function from any thread.
+ *
+ * \since This function is available since SDL 3.4.0.
+ */
+extern SDL_DECLSPEC int SDLCALL SDL_GetSystemPageSize(void);
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 }

Xcode/macOS/SDL3.framework/Versions/A/Headers/SDL_dialog.h

@@ -139,10 +139,12 @@ typedef void (SDLCALL *SDL_DialogFileCallback)(void *userdata, const char * cons
  *                 it will be invoked.
  * \param window the window that the dialog should be modal for, may be NULL.
  *               Not all platforms support this option.
- * \param filters a list of filters, may be NULL. Not all platforms support
- *                this option, and platforms that do support it may allow the
- *                user to ignore the filters. If non-NULL, it must remain
- *                valid at least until the callback is invoked.
+ * \param filters a list of filters, may be NULL. See the
+ *                [`SDL_DialogFileFilter`](SDL_DialogFileFilter#code-examples)
+ *                documentation for examples]. Not all platforms support this
+ *                option, and platforms that do support it may allow the user
+ *                to ignore the filters. If non-NULL, it must remain valid at
+ *                least until the callback is invoked.
  * \param nfilters the number of filters. Ignored if filters is NULL.
  * \param default_location the default folder or file to start the dialog at,
  *                         may be NULL. Not all platforms support this option.